Working With Roles & API Scopes

Learn how to use roles and API scope permissions when working with the Deepgram API and Console.

eepgram uses a tiered system of access control to provide granular access to its endpoints. These tiers include account (or global) permissions and project permissions. Applying different tiers of permissions allows for more granularity at the project level. For example, an account may have the project:kick permission for one project but not for another project.

Account Roles

At the account level, certain permissions imply other specific permissions. For example, an account that has access to the project:write permission also implicitly has access to the project:read permission. Similarly, account:write access implies access to every other account permission.

Project Roles

At the project level, users can have access to several roles, including owner, admin, and member, which, similar to account permissions, imply access to another set of permissions:

Project RoleImplicit Project Permissions
ownerproject:read
project:write
project:write:settings
project:write:destroy
keys:read
keys:write
members:read
members:read:invites
members:read:scopes
members:write
members:write:invites
members:write:scopes
members:write:kick

admins:read
admins:read:invites
admins:read:scopes
admins:write
admins:write:invites
admins:write:scopes
admins:write:kick

owners:read
owners:read:invites
owners:read:scopes
owners:write
owners:write:invites
owners:write:scopes
owners:write:kick

usage:read
usage:write
billing:read
billing:write
adminproject:read
project:write
keys:read
keys:write (restricted to keys they've created)

members:read
members:read:invites
members:read:scopes
members:write
members:write:invites
members:write:scopes
members:write:kick

admins:read
admins:read:invites
admins:read:scopes
admins:write
admins:write:invites
admins:write:scopes
admins:write:kick

owners:read
owners:read:invites
owners:read:scopes

usage:read
usage:write
billing:read
memberproject:read
project:write
keys:read (restricted to keys they've created)
keys:write (restricted to keys they've created)
usage:read
usage:write

Self-Hosted Product Scopes

Deepgram self-hosted users have been assigned self-hosted product scopes in accordance with their contracts. Any user with these scopes may create self-hosted API keys and distribution credentials.

The full list of self-hosted product scopes is as follows:

Product Scope
self-hosted:product:api
self-hosted:product:engine
self-hosted:product:license-proxy
self-hosted:product:dgtools
self-hosted:product:billing
self-hosted:product:hotpepper
self-hosted:product:metrics-server

The self-hosted:products scope can be provided at self-hosted API key or distribution credentials creation time as a short-hand which implies all available self-hosted product scopes.

For example an API key has the self-hosted:product:api, self-hosted:product:engine, and self-hosted:product:license-proxy scopes granted to it. For requests authenticated with that API key, the use of self-hosted:products would imply all of those scopes when included in a key creation request.

Product ScopeExample of Implicit Product Scopes
self-hosted:productsself-hosted:product:api
self-hosted:product:engine
self-hosted:product:license-proxy

Product Scopes and Project Roles

Self-hosted API keys can also be created with Console project roles. To do so, simply include the desired role in the same scopes list as the self-hosted product scopes when submitting the key creation request.

Here is an example of an self-hosted API key which includes both the member project role as well as the self-hosted:products scopes.

{
  "member": {
    "member_id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "[email protected]"
  },
  "api_key": {
    "api_key_id": "6dcd4ce0-2d9e-4f7f-9257-67e9420b9b7f",
    "comment": "Self-hosted API Key Example with both the member role and product scopes.",
    "scopes": [
      "member",
      "self-hosted:product:api",
      "self-hosted:product:engine",
      "self-hosted:product:license-proxy"
    ],
    "created": "2023-06-27T16:59:46.572660Z"
  }
}

What’s Next