Authentication

Learn how to authenticate with Dastra API.

Getting your API secret key

The Dastra REST API uses API keys to authenticate each request. You can manage your keys in the API configuration section of your organization.

You can use an API key for a specific workspace or for the entire organization.

Your API key allows you to perform many actions, so you must keep it safe. Do not share your secret key in public parts of applications such as GitHub, client-side code, etc.

If you want to use OAuth2 authentication with the "authorization_code" flow, you must configure the redirect URLs and allowed CORS origins properly.

API key (X-API-Key)

The simplest way to authenticate is to use the HTTP header X-API-Key containing the private part of your API key, as in the example below:

curl -X 'GET' \
  'https://api.dastra.eu/me' \
  -H 'accept: */*' \
  -H 'X-API-Key: <your private key here>'

OAuth2 "Authorization code" flow

Authorization

The authorization phase is performed by calling the following URL:

https://account.dastra.eu/connect/authorize?
    response_type=code&
    client_id={YOUR_CLIENT_ID}&
    redirect_uri=https://YOUR_APP/callback&
    scope=api1+offline_access&
    state={STATE}

Parameters

Parameter Name	Description
response_type	code
client_id	The public key of your API key configured in your Dastra account
redirect_uri	The URL configured in the Dastra API key. You will be automatically redirected to this page at the end of the authorization process
scope	api1 => mandatory offline_access => to obtain a refresh_token (long sessions)
state	A random string generated by your application to prevent cross-site request forgery (CSRF) attacks. See Mitigate CSRF Attacks With State Parameters. Client libraries usually handle this automatically

OAuth2 "Client credentials" flow

Authentication method

API authentication is based on the OAuth2 protocol using the "Client credentials" flow. This authentication mode should only be used for server-to-server requests and must never be used on the client side (e.g., JavaScript SPA).

Getting the token

POST https://account.dastra.eu/connect/token

Perform a token request using BASIC headers.

Headers

Name	Type	Description
Authorization	Basic {base64("{PublicKey}:{PrivateKey}")}

Request Body

Name	Type	Description
grant_type	string	client_credentials
scope	string	api1

200: OK - Access Token for REST API Operations

{
  "access_token": "tNQoqsSePv0DnSSNVJv1aDxzSFh9H2z3YBKtuBKqWAU",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "api1"
}

Once you have retrieved an access_token, you can call any REST API endpoint using this token as a "Bearer token".

For example, to get the list of your workspaces:

GET https://api.dastra.eu/v1/workspaces

Retrieve the list of Dastra workspaces.

Headers

Name	Type	Description
Authorization	Bearer {access_token}

200: OK

{
  "items": [
    {
      "id": 1,
      "tenantId": 1,
      "label": "My data company",
      "logoUrl": null,
      "state": "Active",
      "permissions": null,
      "dataSubjectArchivedRetentionDays": null,
      "nbEntities": 1
    },
    {
      "id": 2,
      "tenantId": 1,
      "label": "My test workspace",
      "logoUrl": null,
      "state": "Active",
      "permissions": null,
      "dataSubjectArchivedRetentionDays": null,
      "nbEntities": 1
    },
    {
      "id": 3,
      "tenantId": 1,
      "label": "My experimentation workspace",
      "logoUrl": null,
      "state": "Active",
      "permissions": null,
      "dataSubjectArchivedRetentionDays": null,
      "nbEntities": 0
    }
  ],
  "total": 3
}

All requests must be made over HTTPS and always from the server side. Requests without authentication will fail with error code 401.

See the API reference here: https://api.dastra.eu/swagger/index.html