Working with Roles and Scopes
Learn how to use roles and permissions when working with the Deepgram API and Console.
Deepgram 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 Role | Implicit Project Permissions |
---|---|
owner | project: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 |
admin | project:read project:write 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 usage:read usage:write billing:read |
member | project:read project:write keys:read keys:write usage:read usage:write |
On-premises Product Scopes
The projects of Deepgram On-premises (on-prem) users have been granted on-premises product scopes based on their contract. Any user with these scopes may create on-premises API keys and on-premises distribution credentials.
The full list of on-prem product scopes is as follows:
Product Scope |
---|
onprem:product:api onprem:product:engine onprem:product:license-proxy onprem:product:dgtools onprem:product:billing onprem:product:hotpepper onprem:product:metrics-server |
The onprem:products
scope can be provided at on-prem API key creation time as a short-hand which implies all available on-prem product scopes. For example, suppose an API key has the onprem:product:api
, onprem:product:engine
, and onprem:product:license-proxy
scopes granted to it. For requests authenticated with that API key, the use of onprem:products
would imply all of those scopes when included in a key creation request.
Product Scope | Implicit Product Scopes |
---|---|
onprem:products | onprem:product:api onprem:product:engine onprem:product:license-proxy |
Product Scopes and Project Roles
On-prem API keys can also be created with Console project roles (in fact this is enforced when a key is created by the UI). To do so, simply include the desired role in the same scopes
list as the on-prem product scopes when submitting the key creation request.
Here is an example of an on-prem API key which includes both the member
project role as well as the onprem:products
scopes.
{
"member": {
"member_id": "550e8400-e29b-41d4-a716-446655440000",
"email": "[email protected]"
},
"api_key": {
"api_key_id": "6dcd4ce0-2d9e-4f7f-9257-67e9420b9b7f",
"comment": "On-prem API Key Example with both the member role and product scopes.",
"scopes": [
"member",
"onprem:product:api",
"onprem:product:engine",
"onprem:product:license-proxy"
],
"created": "2023-06-27T16:59:46.572660Z"
}
}
Updated 5 months ago