Use platform token authentication

This is for:

Developer

Platform tokens are special JSON web tokens that can be used to query Coveo APIs as a specific user. You can generate platform tokens by making a call to the Authorization Server API.

Request a platform token

To request a platform token, make a POST request to https://platform.cloud.coveo.com/rest/organizations/<ORGANIZATION_ID>/tokens. You must also specify a validityPeriod in your request, after which the token will expire. The default is 24 hours (validityPeriod=PT24H).

You must authenticate with a valid API key whose privileges match those needed for your use case. For example:

  • To create a platform token to perform authenticated search as any user, use an API key that was created using the Authenticated search template.

  • To create a platform token to send usage analytics data to your organization as any user, use an API key that was created using the Usage analytics template.

To test the service on Coveo, use the Swagger UI.

Examples

  1. Creating a platform token to perform authenticated search:

    POST https://platform.cloud.coveo.com/rest/organizations/<ORGANIZATION_ID>/tokens?validityPeriod=PT24H HTTP/1.1
​
Content-Type: application/json
Accept: application/json
Authorization: Bearer **********-****-****-****-************

    Payload:

    {
  "body": {
    "additionalConfiguration": {
      "search": {
        "userIds": [
          {
            "name": "asmith@example.com",
            "provider": "Email Security Provider",
            "type": "User"
          }
        ]
      }
    },
    "organizationId": "<ORGANIZATION_ID>",
    "privileges": [
      {
        "level": "NORMAL",
        "owner": "SEARCH_API",
        "targetDomain": "IMPERSONATE",
        "targetId": "*",
        "type": "ENABLE"
      }
    ]
  }
}

    200 OK response body:

    {
  "token": "fzKjcHdjPJKJVaJ2OjK0fzK2CI6dHJ1ZSwiZXhwIjoxNDY4Njk2NzEwLCJpYXQiOjE0lQGN..."
}

  2. Creating a platform token to send usage analytics data to your organization:

    POST https://platform.cloud.coveo.com/rest/organizations/<ORGANIZATION_ID>/tokens?validityPeriod=PT24H HTTP/1.1
​
Content-Type: application/json
Accept: application/json
Authorization: Bearer **********-****-****-****-************

    Payload:

    {
  "body": {
    "additionalConfiguration": {
      "analytics": {
        "event": {
          "userDisplayName": "Alice Smith",
          "userId": "12345678"
        }
      }
    },
    "organizationId": "<ORGANIZATION_ID>",
    "privileges": [
      {
        "level": "NORMAL",
        "owner": "USAGE_ANALYTICS",
        "targetDomain": "IMPERSONATE",
        "targetId": "*",
        "type": "ENABLE"
      }
    ]
  }
}

    200 OK response body:

    {
  "token": "fzKjcHdjPJKJVaJ2OjK0fzK2CI6dHJ1ZSwiZXhwIjoxNDY4Njk2NzEwLCJpYXQiOjE0lQGN..."
}

Get a list of privileges

To get a list of the privileges that you can add to your platform token, make a GET request to https://platform.cloud.coveo.com/rest/organizations/<ORGANIZATION_ID>/privileges/platformtokens.

You must authenticate with a valid API key that was created using the Custom template and which has the View access level on the Organization domain.