Axeptio API use OAuth1.0. You pass a Bearer Token in the Authorization header of your requests or append an ?access_token={your Token} to the URLS you request. Any unauthenticated request on a private resource will result in a 403 HTTP Error.
The API version is the first part of the path. Only v1 for now.
Axeptio API exposes different services. They are the second part of the paths:
/app
is the business layer of Axeptio, used to collect / import / export consent proofs
/vault
is the document store where we put all the configurations (cookies, projects, etc.)
/auth
is the authentification gateway that issues access tokens and allow 3rd party logins
/webhooks
allows customers to register endpoints that we will call on specific events
/assets
is a file upload service that can handle and serve optimized renders of image files (using imgix)
/publish
is the orchestration service that packages and deploy the project configurations (relies on AWS S3 and Cloudfront)
/billing
is the Stripe Billing gateway service
Authentification, password reset, invitations are all handled by the Auth service. Users can have several identities, provided by social login providers or by the API itself.
To create an API user account with a local identity, you have to proceed to a local signup flow :
POST https://api.axept.io/v1/auth/local/signup
{"displayName": "John Doe","username": "johndoe@mail.com","email": "johndoe@mail.com","password": "xyz"}
If the username and emails aren't already in use, you'll receive a payload containing the access token. This token has a limited lifetime (15d). Nota: the API does not enforce password complexity nor renewal. This is actually delegated to the application that makes the call.
{ "token": "d79b641e-8b58-42e1-87bb-55f95b981479" }
This token can be appended to the URLs: ?access_token=${response.body.token}
Or passed as a HTTP header: Authorization: Bearer ${response.body.token}
Sign in with the Axeptio API is basically getting a fresh token. To do this:
POST https://api.axept.io/v1/auth/local/signin
{"username": "johndoe@mail.com","password": "xyz"}
If you intend to sign in programmatically, you will have to store the user password. This is because the authentification service is not designed to be called that way in the first place. We'll be working on a route to renew an access_token programmatically in the next months.
Create and manipulate Axeptio documents
This service is a RESTful CRUD that allows us to store and manipulate various types of documents. Think of it like a RESTful ORM over a document-oriented DB. Every request to the vault service has to be authentified.
POST https://api.axept.io/vault/${resource}
{"property": "value"}
PUT https://api.axept.io/vault/${resource}/${documentId}
DELETE https://api.axept.io/vault/${resource}/${documentId}
POST https://api.axept.io/vault/${resource}/${documentId}/users
{ "userId": "5a968b6b4f27e574ce3b4f20" }
A client configuration is based on a Project
document. This project contains:
basic information (websiteURL, title, organization id)
design and customization props (colors, fonts, etc.)
billing data (subscription, payment source, etc.)
Data Protection Officer identity
To create a working project, only websiteURL and title are required. If you don't specify an organization id ,the project will be considered as free tier, as long as the subscription process has not been completed on the Axeptio admin app.
POST/PUT/GET/DELETE https://api.axept.io/v1/vault/projects(/${project._id})
POST/PUT/GET/DELETE https://api.axept.io/v1/vault/cookies(/${cookieConfiguration._id})
You need a working project to create a coookie configuration. A cookie configuration is composed of the following props:
steps
: an array of step
, corresponding to the consecutive steps in the cookie widget.
strings
: an object containing the user-facing messages of the widget
consentWidgetStrings
: an object containing the user-facing messages for the consent proof collection
settings
: an object containing apparition and UX settings
projectId
: the ID of the project (used for joining projects and configuration in the admin panel)
It is a bit more complex, composed of the following props:
name
is the unique string identifier
title
, topTitle
, subTitle
, : plain text strings
message
: HTML text content displayed under the titles
image
URL or asset identifier for the upper right image
layout
is a string that can take one of the following options:
welcome
category
info
: (Not free)
iab
: (Not free)
soft_consent
: (Not free)
vendors
is an array containing vendor objects (not compatible with welcome
layout)
strings
is an object overriding the Cookie Configuration strings
prop
timeout
number in ms, is the time before the step goes away, only available in soft_consent
and info
layouts.
showToggleAllSwitch
boolean that dictates whether there's a big toggle switch to rule all the vendors or not
It represents one of your third party cookie vendor / service provider.
{"name": "google_analytics","title": "Google Analytics","shortDescription": "Permet d'analyser les statistiques de consultation de notre site","longDescription": "Indispensable pour piloter notre site internet, il permet de mesurer des indicateurs comme l’affluence, les produits les plus consultés, ou encore la répartition géographique des visiteurs.","domain": "analytics.google.com","policyUrl": "https://support.google.com/analytics/answer/6004245?hl=fr"}
POST/PUT/GET/DELETE https://api.axept.io/v1/vault/processings(/${consent._id})
A consent box configuration is made of the following properties:
projectId
: string
ID of the project (used to join project and Consent box in the admin panel)
title
: string
subTitle
: string
picture
: url
icon displayed in the top right placeholder
message
: text of the widget (can be html)
purpose
: Purpose of the data processing (GDRP compliant explanation for the data processing)
buttons
: it's an array
that contains the definition of each button displayed at the bottom of the consent box. This definition consists of the following fields : text
, color
(primary or default), value
confirmations
: object
defines the content and behaviour of confirmation screens. Each screen is described by the fields title
, message
and backButtonText
processors
: an array
of data processors objects
. A processor is defined by the properties name
, shortDescription
, role
, and website
.
personalDataTypes
: an array of strings
describing every type of personal data involved in the data processing (ex: 'first name', 'last name', 'phone number', etc.)
automatedDecisions
: boolean
automatedDecisionsContact
: text person to contact in case of automated decisions related claim
automatedDecisionsDetails
: text GDPR compliant explanation of automated decisions
consentWithdraw
: text GDPR compliant explanation of the consent withdrawal procedure
storageDuration
: number in month, how long are the data collected will be stored.
POST/PUT/GET/DELETE https://api.axept.io/v1/vault/contracts(/${consent._id})
To create a widget for contractual consents or approval, you need to declare it in the "contracts" collection of the vault service. These contract box work by simply opening a target file or resource in a new tab of the browser, but the consent collection mechanic stay the same.
A contract box configuration is made of the following properties:
projectId
: string
ID of the project (used to join project and Consent box in the admin panel)
file
: string
URL of the file that will be opened in the browser.
title
: string
subTitle
: string
name
: string
attribute of the <input>
checkbox that will be appended to the parent form
message
: text of the widget (can be html)
idRequired
: Boolean that will be translated to required="required"
in the <input>
tag.
buttons
: it's an array
that contains the definition of each button displayed at the bottom of the consent box. This definition consists of the following fields : text
, color
(primary or default), value
Publish a configuration consists of the following steps:
User requests a publish for a specific project
The Axeptio API creates a Publish Job and returns its ID immediately
Using this ID, the calling application polls the API to get status updates about the job, respecting the specified timeout
property in the payload or defaulting to 500ms between polls.
In the meantime, the Publish service updates the job at each step of the process and...
Fetches all the widgets and creates an optimized build of every config
Checks if the resulting file exceed the free tier limitations
Checks if there's an organization attached to the project.
Checks both project and organization subscription status on Stripe
Uploads the config file on our AWS S3 Bucket
Invalidate the file in our Cloudfront Distribution.
When it's done, the publish job is marked as completed and the config is live.
To create a job, simply hit https://api.axept.io/v1/publish/jobs/${project._id}
with a POST request (no payload required). You shall receive a similar payload:
{"links": {"self": "https://api.axept.io/v1/publish/jobs/5d09f8e7c4211a305bb2afbd/5d821d98ebc71716a404f222"},"timeout": 500,"initiator": [],"started": "2019-09-18T12:05:44.175Z","projectId": "5d09f8e7c4211a305bb2afbd","initiatedBy": "5a6b405a9cffce2ad8a02683","status": "started","_id": "5d821d98ebc71716a404f222"}
You can then use the payload.links.self
to start your polling. Beware, there is no quota policy enforced, we expect our customer to be responsible. Do not DDOS the API by forgetting to delay your polling.
Once the process is done, you will receive the URL to the CDNized config file, directly in the payload:
{"links": {"self": "https://api.axept.io/v1/publish/jobs/5d09f8e7c4211a305bb2afbd/5d821d98ebc71716a404f222"},"timeout": 500,"initiator": [],"_id": "5d821d98ebc71716a404f222","started": "2019-09-18T12:05:44.175Z","projectId": "5d09f8e7c4211a305bb2afbd","initiatedBy": "5a6b405a9cffce2ad8a02683","status": "complete","message": "success","completed": "2019-09-18T12:07:24.941Z","url": "https://client.axept.io/5d09f8e7c4211a305bb2afbd.json"}