Skip to main content

API Overview

The Digital.ai Platform API reference documentation describes the HTTP method, path, and parameters for every operation. It also displays example requests and responses for each operation.

For more information, see API Reference.

The Digital.ai Platform API is a REST API, which means that you can use standard HTTP methods (GET, POST, PATCH, PUT, and DELETE) to retrieve, submit, change, and delete data. To ensure data privacy, the API is served over HTTPS; unencrypted HTTP is not supported.

REST also uses Uniform Resource Identifiers (URIs) and most often JavaScript Object Notation (JSON) conventions for data exchange between the client and the server.

How It Works​

Each interface provides a set of API resources that let you perform various Platform tasks. Each resource has a URL (or endpoint) on the Digital.ai server. To call a resource, you send a request to the appropriate URL, and the Digital.ai server responds with JSON-formatted data.

When you make a request to the REST API, you will specify an HTTP method and a path. Additionally, you might also specify request headers and path, query, or body parameters. The API will return the response status code, response headers, and a response body.

The REST operations GET, POST, PATCH, PUT, and DELETE are described as follows:

  • GET - The GET method is used to retrieve/request data for a resource.
  • POST - The POST method is used to create a data resource or invoke an operation resource.
  • PATCH - The PATCH method is used to create or update a sub-resource within the target resource. If the target resource instance does not exist, the server will not create it.
  • PUT - The PUT method is used to create or replace the target resource.
  • DELETE - The DELETE method is used to delete the target resource.

Authentication​

Rest API authentication is used to authenticate users and applications when performing API tasks. Authentication is a must to ensure that APIs are secure and accessible only to authorized users.

Digital.ai Platform supports Token Authentication. The token can be obtained via Basic or OAuth mechanisms but the API accepts only bearer tokens.

The majority of our API endpoints are secured, so you must authenticate before use. However, in other scenarios, the service may require separate authentication with the Platform. This section provides a detailed explanation of the authentication process for such services.

To consume our APIs, whether through Swagger, Postman, Curl, or a custom script, you must use the OAuth 2.0 Client Credentials grant. Before you can authenticate, you need to create For API Use application that represents your client. Once the Client is created, you can use the associated client_id and client_secret to obtain an access token.

For more information refer RFC 6749

Perform the following steps to do this action:

Prerequisite​

You must have a Client that you can use to authenticate. This client should be created as For API Use application.

If you don’t have one yet, follow the steps below to create it.

Create Client​

To create a client, you need to create an application:

note

You only need to do this once. Once you have a client, it remains valid until you delete it.

  1. Log in to Digital.ai Platform.

  2. In the left navigation, click Applications.

    Alternatively, you can click the Create application button on the Platform Overview page.

  3. In Select application, choose For API Use as the application type.

  4. In Instance name, assign the application's user defined name for your application.

  5. Click Next to proceed to the Advanced configuration section.

  6. Accept the default values on the Advanced configuration and Mappers pages.

  7. On the Get client ID & secret page save the Client ID and Client Secret values.

  8. Click Complete to finish creating the application and the associated client.

2. Use /token to get a token (as described in the OIDC spec)​

To get a token:

  1. Determine token URL

    a. Call this endpoint, provide your vanity domain in the ?hint= parameter.

    https://api.us.digital.ai/identity/v1/accounts/{account_identifier}/.well-known/openid-configuration/?hint=<vanity domain here>

    For example:

    curl -X GET "https://api.digital.ai/identity/v1/accounts/auth/configuration/?hint=champagne" -H "accept: application/json"

    b. In the response, retrieve the token_endpoint value, for example:

    https://identity.us.digital.ai/auth/realms/champagne/protocol/openid-connect/token

For more information refer RFC 6749

  1. Prepare POST request with the following details:

    a. Headers:

    • content-type = application/x-www-form-urlencoded

    • Default headers usually ok for most HTTP Clients

    b. Body: (x-www-form-urlencoded)

    • grant_type = client_credentials

    • client_id = insert Client ID from "Create Client" section.

    • client_secret = insert Client Secret from "Create Client" section.

    • scope = openid dai-svc

    c. Retrieve access_token from token endpoint response.

Example request:

curl --location --request POST \
'https://identity.us.digital.ai/auth/realms/champagne/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=<client id retrieved from create client section>' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_secret=<client secret retrieved from create client section>' \
--data-urlencode 'scope=openid dai-svc'

Example response:

{
   "access_token": "SlAV32hkKG",
   "token_type": "Bearer",
   ............
}

3. Use the token to authenticate a request​

To interact with the API:

  1. Identify the API endpoint you want to call.

  2. Include the access_token in the Authorization Header:

    a. Authorization = Bearer (insert access token)

Example request:

curl --location --request GET 'https://api.us.digital.ai/licensing/products' \
--header 'Authorization: Bearer <access_token>'
Last updated on