Authentication

Send the API keyCopy Anchor Link

Send the API key in the Authorization header of each request, with the Bearer scheme.

curl https://api.deepscout.ai/v1/projects \
  -H "Authorization: Bearer $SCOUT_API_KEY"

A request without a key gets 401 with the code NOT_AUTHENTICATED. A request with an unknown or revoked key gets 401 with the code INVALID_API_KEY.

Key scopesCopy Anchor Link

An API key always belongs to you, the user who created it. Its scope sets where the key works.

Use a PROJECT key to keep an integration or an agent inside one project. With this key:

• GET /projects shows only the project of the key.
• A request for another project gets the same error as a project that you cannot access, for example 404 PROJECT_NOT_FOUND.
• The account, customer and billing endpoints answer 403 INSUFFICIENT_SCOPE. The key cannot create keys or projects, and it cannot read or top up the credit.
• The key has your role in the project. With the ADMIN or EDITOR role, it can approve jobs, and the jobs use the credit of the customer.

Use a USER key for a script that also manages keys, projects or the credit.

A request that needs project_id with a USER key also needs it with a PROJECT key. The export download, GET /exports/{dataset}, is the only exception. With a PROJECT key, it always uses the project of the key, and project_id is optional.

Manage keysCopy Anchor Link

You can manage keys in the console, under Settings → API keys, or with the API.

The API shows the full key only one time, in the response to the create request. The list shows only the last four characters, in key_suffix.

curl https://api.deepscout.ai/v1/account/api-keys \
  -H "Authorization: Bearer $SCOUT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Data warehouse", "project_id": null}'

{
  "api_key": "Xb3v...full-key...9QaL",
  "key_id": "key_01k7c4m2n3p4q5r6s7t8v9w0x1",
  "scope": "USER"
}

Send project_id: null for a USER key, or the ID of a project for a PROJECT key.

You can have more than one active key. To rotate a key without downtime, create the new key, change your integration to use it, and then revoke the old key.

RolesCopy Anchor Link

What a key can do also depends on your roles. A key has the roles of the user who created it.

Customer rolesCopy Anchor Link

A customer is the account that pays. Each user has a role in each customer: OWNER, ADMIN or MEMBER. GET /customers shows your role.

Project rolesCopy Anchor Link

Each user also has a role in each project: ADMIN, EDITOR or VIEWER. When you create a project, you become its ADMIN.

A request without the needed role gets 403 with the code INSUFFICIENT_ROLE or PROJECT_ACCESS_DENIED. A project that you cannot access gets 404 PROJECT_NOT_FOUND. Updating a project, removing a website and creating a project key answer 403 PROJECT_ACCESS_DENIED instead.