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.)

• /vendors is the document store where you can find all axeptio vendors

• /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

{
  "displayName": "John Doe",
  "username": "[e-mail]",
  "email": "[e-mail]",
  "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

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": "[e-mail]",
  "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.

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}

{
  "property": "value"
}

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

{ "userId": "5a968b6b4f27e574ce3b4f20" }

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

• 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)

  • soft_consent: (Not free)

• vendors is an array containing vendor ids (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

Get a Vendor

Axeptio vendors vs Custom vendors

To add vendors to your configuration, you can either use a vendor managed by Axeptio or create a custom vendor. By default, we recommend using Axeptio vendors. These vendors are regularly updated and automatically translated into the language of your cookie configuration, with regular updates and additions.

However, there are two cases where you may want to create your own vendor:

• The vendor does not exist in Axeptio's vendor database.

• You are using a language that is not yet available.

In both cases, we need the vendor id to add it to your cookie configuration.

Browse Axeptio vendors

GET https://api.axept.io/v1/vendors/solutions?data.__enable[bool]=true&data.deprecated[bool]=false&embed=categories&embed=company

These results are paginated. You can control pagination using the page and perPage parameters. The current pagination state can be found in the headers:

X-Last-Page: 13
X-Page: 1
X-Per-Page: 100
X-Total-Count: 1225

An id is used to identify each vendor, which we will use in our cookie configuration. You will also find the main information about a vendor in the data property, which includes the following properties:

• title: The display name of the solution.

• shortDescription and longDescription: Short and long descriptions of the solution.

• website: A link to the product.

• policyUrl: A link to the privacy policy.

• categories: The categories in which this vendor belongs.

• company: The company that publishes the solution.

Create and browse Custom vendors

Custom Vendors are managed within a collection in the vault service. The API documentation provides methods for accessing, creating, and deleting an object within a collection.

POST/PUT/GET/DELETE https://api.axept.io/v1/vault/vendors(/${vendorId})

A vendor must have the following structure:

{
    "name": "google_analytics",
    "title": "Google Analytics",
    "shortDescription": "Allows analyzing website visit statistics",
    "longDescription": "Essential for managing our website, it enables measurement of metrics such as traffic, most viewed products, and geographical distribution of visitors.",
    "domain": "analytics.google.com",
    "policyUrl": "https://support.google.com/analytics/answer/6004245?hl=en"
}

You can find the id either during the creation of your vendor or by browsing the list of vendors.

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:

{
  "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"
}