API Documentation

General information
Authenticating requests
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.
Versioning
The API version is the first part of the path. Only v1 for now.
Services
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
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.
Sign up
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
1
{
2
  "displayName": "John Doe",
3
  "username": "[email protected]",
4
  "email": "[email protected]",
5
  "password": "xyz"
6
}
Copied!
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.
1
{ "token": "d79b641e-8b58-42e1-87bb-55f95b981479" }
Copied!
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
Sign in with the Axeptio API is basically getting a fresh token. To do this:
POST https://api.axept.io/v1/auth/local/signin
1
{
2
  "username": "[email protected]",
3
  "password": "xyz"
4
}
Copied!
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.
The vault service
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.
Create an instance of this resource (send the "body" of the document directly)
POST https://api.axept.io/vault/${resource}
1
{
2
  "property": "value"
3
}
Copied!
Update an instance of a resource
PUT https://api.axept.io/vault/${resource}/${documentId}
Delete an instance of a resource
DELETE https://api.axept.io/vault/${resource}/${documentId}
Add a user to the instance
POST https://api.axept.io/vault/${resource}/${documentId}/users
1
{ "userId": "5a968b6b4f27e574ce3b4f20" }
Copied!
Creating a project (aka: website)
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
Project resource example
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})
Creating a cookie configuration
POST/PUT/GET/DELETE https://api.axept.io/v1/vault/cookies(/${cookieConfiguration._id})
The Configuration object
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)
The Step object
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
The Vendor object
It represents one of your third party cookie vendor / service provider.
1
{
2
  "name": "google_analytics",
3
  "title": "Google Analytics",
4
  "shortDescription": "Permet d'analyser les statistiques de consultation de notre site",
5
  "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.",
6
  "domain": "analytics.google.com",
7
  "policyUrl": "https://support.google.com/analytics/answer/6004245?hl=fr"
8
}
Copied!
Creating a Consent Box
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: urlicon 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.
Consent Box Resource Example
Creating a Contract Box
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 client configuration
Publish a configuration consists of the following steps:
1.
User requests a publish for a specific project
2.
The Axeptio API creates a Publish Job and returns its ID immediately
3.
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.
4.
In the meantime, the Publish service updates the job at each step of the process and...
1.
Fetches all the widgets and creates an optimized build of every config
2.
Checks if the resulting file exceed the free tier limitations
3.
Checks if there's an organization attached to the project.
4.
Checks both project and organization subscription status on Stripe
5.
Uploads the config file on our AWS S3 Bucket
6.
Invalidate the file in our Cloudfront Distribution.
5.
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:
1
{
2
  "links": {
3
    "self": "https://api.axept.io/v1/publish/jobs/5d09f8e7c4211a305bb2afbd/5d821d98ebc71716a404f222"
4
  },
5
  "timeout": 500,
6
  "initiator": [],
7
  "started": "2019-09-18T12:05:44.175Z",
8
  "projectId": "5d09f8e7c4211a305bb2afbd",
9
  "initiatedBy": "5a6b405a9cffce2ad8a02683",
10
  "status": "started",
11
  "_id": "5d821d98ebc71716a404f222"
12
}
Copied!
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:
1
{
2
  "links": {
3
    "self": "https://api.axept.io/v1/publish/jobs/5d09f8e7c4211a305bb2afbd/5d821d98ebc71716a404f222"
4
  },
5
  "timeout": 500,
6
  "initiator": [],
7
  "_id": "5d821d98ebc71716a404f222",
8
  "started": "2019-09-18T12:05:44.175Z",
9
  "projectId": "5d09f8e7c4211a305bb2afbd",
10
  "initiatedBy": "5a6b405a9cffce2ad8a02683",
11
  "status": "complete",
12
  "message": "success",
13
  "completed": "2019-09-18T12:07:24.941Z",
14
  "url": "https://client.axept.io/5d09f8e7c4211a305bb2afbd.json"
15
}
Copied!