Keys

Keys are associated with Deepgram Projects. They enable you to use the Deepgram API, identify the Project calling the API, and associate usage information with Projects. Keys are assigned Scopes, which determine which actions they can be used to perform in the associated Project. For each Project, you can create multiple Keys and assign different Scopes for each Key.

Get Keys

Retrieves keys for the specified project. If the authenticated account has access to the members:read, admins:read, and owners:read project scopes, it will list all keys for the project. Otherwise, it will only list keys that belong to the authenticated account.

Required account/project scope(s): keys:read. Optional project scope(s): members:read, admins:read, owners:read.

Path Parameters

project_id: uuid

Unique identifier of the project for which you want to get keys.

Responses

Status	Description
200 Success	Keys found.

Response Schema

api_keys: array

Array of associated Member and API Key objects.
- member: object
  
  Member object.
  - member_id: uuid
    
    Unique identifier of member.
  - email: string
    
    Email address of member.
  - first_name: string
    
    First name of member. If no first name exists, this item will not be returned.
  - last_name: string
    
    Last name of member. If no last name exists, this item will not be returned.
- api_key object
  
  API Key object.
  - api_key_id: uuid
    
    Unique identifier of API Key.
  - comment: string
    
    Comments associated with API Key.
  - scopes: array
    
    Array of scopes associated with API Key.
  - tags: array
    
    Array of tags associated with API Key. If no tags exist, this item will not be returned.
  - created: string
    
    Date and time when API Key was created.
  - expiration_date: string
    
    Date and time when API Key will expire. If no expiration date exists, this item will not be returned.

endpoint

GET /projects/{project_id}/keys

Get Keys

# cURL

curl --request GET \
  --url 'https://api.deepgram.com/v1/projects/{project_id}/keys' \
  --header 'Authorization: Token <YOUR_DEEPGRAM_API_KEY>' \
  --header 'content-type: application/json'

# python

import http.client

conn = http.client.HTTPSConnection("api.deepgram.com")

headers = {
    'Authorization': "Token <YOUR_DEEPGRAM_API_KEY>",
    'content-type': "application/json"
    }

conn.request("GET", "/v1/projects/{project_id}/keys", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

// .NET

using Deepgram;

var deepgram = new DeepgramClient(new Credentials("YOUR_DEEPGRAM_API_KEY"));
var keys = await deepgram.Keys.ListKeysAsync("DEEPGRAM_PROJECT_ID");

// Node.js

const http = require('https')

const options = {
  method: 'GET',
  hostname: 'api.deepgram.com',
  port: null,
  path: '/v1/projects/{project_id}/keys',
  headers: {
    Authorization: 'Token <YOUR_DEEPGRAM_API_KEY>',
    'content-type': 'application/json',
  },
}

const req = http.request(options, function (res) {
  const chunks = []

  res.on('data', function (chunk) {
    chunks.push(chunk)
  })

  res.on('end', function () {
    const body = Buffer.concat(chunks)
    console.log(body.toString())
  })
})

req.end()

# PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.deepgram.com/v1/projects/{project_id}/keys",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Token <YOUR_DEEPGRAM_API_KEY>",
    "content-type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

# Ruby

require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://api.deepgram.com/v1/projects/{project_id}/keys")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Token <YOUR_DEEPGRAM_API_KEY>'
request["content-type"] = 'application/json'

response = http.request(request)
puts response.read_body

response

{
  "api_keys": [
    {
      "member": {
        "member_id": "uuid",
        "email": "string",
        "first_name":"string",
        "last_name":"string"
      },
      "api_key": {
        "api_key_id": "uuid",
        "comment": "string",
        "scopes": [
          "string"
        ],
        "tags": [
          "string"
        ],
        "created": "YYYY-MM-DDThh:mm:ss.sTZD",
        "expiration_date":"YYYY-MM-DDThh:mm:ss.sTZD"
      }
    }
  ]
}

Get Key

Retrieves basic information about the specified key. If the authenticated account has access to the members:read, admins:read, and owners:read project scopes, it will retrieve the information for any key in the project. Otherwise, it will retrieve the information for only one of the keys that belong to the authenticated account.

Required account/project scope(s): keys:read. Optional project scope(s): members:read, admins:read, owners:read.

Path Parameters

project_id: uuid

Unique identifier of the project for which you want to retrieve information.

key_id: uuid

Unique identifier of the key that you want to retrieve.

Responses

Status	Description
200 Success	Key found.
404 Not Found	A key with the specified key ID in the specified project was not found.

Response Schema

member: object

Member object.
- member_id: uuid
  
  Unique identifier of member.
- email: string
  
  Email address of member.
- first_name: string
  
  First name of member. If no first name exists, this item will not be returned.
- last_name: string
  
  Last name of member. If no last name exists, this item will not be returned.
api_key object

API Key object.
- api_key_id: uuid
  
  Unique identifier of API Key.
- comment: string
  
  Comments associated with API Key.
- scopes: array
  
  Array of scopes associated with API Key.
- tags: array
  
  Array of tags associated with API Key. If no tags exist, this item will not be returned.
- created: string
  
  Date and time when API Key was created.
- expiration_date: string
  
  Date and time when API Key will expire. If no expiration date exists, this item will not be returned.

endpoint

GET /projects/{project_id}/keys/{key_id}

Get Key

# cURL

curl --request GET \
  --url 'https://api.deepgram.com/v1/projects/{project_id}/keys/{key_id}' \
  --header 'Authorization: Token <YOUR_DEEPGRAM_API_KEY>' \
  --header 'content-type: application/json'

# python

import http.client

conn = http.client.HTTPSConnection("api.deepgram.com")

headers = {
    'Authorization': "Token <YOUR_DEEPGRAM_API_KEY>",
    'content-type': "application/json"
    }

conn.request("GET", "/v1/projects/{project_id}/keys/{key_id}", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

// .NET

using Deepgram;

var deepgram = new DeepgramClient(new Credentials("YOUR_DEEPGRAM_API_KEY"));
var key = await deepgram.Keys.GetKeyAsync("DEEPGRAM_PROJECT_ID", "KEY_ID");

// Node.js

const http = require('https')

const options = {
  method: 'GET',
  hostname: 'api.deepgram.com',
  port: null,
  path: '/v1/projects/{project_id}/keys/{key_id}',
  headers: {
    Authorization: 'Token <YOUR_DEEPGRAM_API_KEY>',
    'content-type': 'application/json',
  },
}

const req = http.request(options, function (res) {
  const chunks = []

  res.on('data', function (chunk) {
    chunks.push(chunk)
  })

  res.on('end', function () {
    const body = Buffer.concat(chunks)
    console.log(body.toString())
  })
})

req.end()

# PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.deepgram.com/v1/projects/{project_id}/keys/{key_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Token <YOUR_DEEPGRAM_API_KEY>",
    "content-type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

# Ruby

require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://api.deepgram.com/v1/projects/{project_id}/keys/{key_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Token <YOUR_DEEPGRAM_API_KEY>'
request["content-type"] = 'application/json'

response = http.request(request)
puts response.read_body

response

{
  "member": {
    "member_id":"uuid",
    "email":"string",
    "first_name":"string",
    "last_name":"string"
  },
  "api_key": {
    "api_key_id":"uuid",
    "comment":"string",
    "scopes": [
      "string"
    ],
    "tags": [
      "string"
    ],
    "created":"YYYY-MM-DDThh:mm:ss.sTZD",
    "expiration_date":"YYYY-MM-DDThh:mm:ss.sTZD"
  }
}

Create Key

Creates a new key in the specified project. You must create your first API Key using the Deepgram Console.

Required account/project scope(s): keys:write.

Path Parameters

project_id: uuid

Unique identifier of the project for which you want to create a key. Required.

Request Body Schema

comment: string

Comments associated with the key you would like to create. Must be between 1 and 128 characters long, not including whitespace. Required.

tags: array

Tags associated with the key you would like to create. Optional.

scopes: array

Scopes for the key you would like to create. Required.

Scopes cannot be empty.

The requested account scopes for the new key cannot exceed the scopes of the authenticated account making the request.

The requested project scopes for the new key cannot exceed the scopes of the authenticated account making the request.

expiration_date: datetime

Date on which the key you would like to create should expire. Optional.

If no time zone is specified, defaults to Coordinated Universal Time (UTC).

For each key, you may specify either an expiration_date or a time_to_live_in_seconds, but not both.

time_to_live_in_seconds: number

Length of time (in seconds) during which the key you would like to create will remain valid. Optional.

For each key, you may specify either an expiration_date or a time_to_live_in_seconds, but not both.

Responses

Status	Description
201 Success	Key created.

Response Schema

api_key_id: uuid

Unique identifier of the API Key.
key: string

Value of the API Key. This is the only chance to read the Key value; it cannot be recovered later.
comment: string

Comments associated with the API Key.
scopes: array

Project scopes associated with the API Key.
tags: array

Tags associated with the API Key. If no tags exist, this item will not be returned.
created: string

Date and time when the API Key was created.
expiration_date: string

Date and time when the API Key expires. If no expiration date exists, this item will not be returned.

endpoint

POST /projects/{project_id}/keys

Create Key

# cURL

curl --request POST \
  --url 'https://api.deepgram.com/v1/projects/{project_id}/keys' \
  --header 'Authorization: Token <YOUR_DEEPGRAM_API_KEY>' \
  --header 'content-type: application/json' \
  --data '{"comment":"string","scopes":["string"]}'

# python

import http.client

conn = http.client.HTTPSConnection("api.deepgram.com")

payload = "{\"comment\":\"string\",\"scopes\":[\"string\"]}"

headers = {
    'content-type': "application/json",
    'Authorization': "Token <YOUR_DEEPGRAM_API_KEY>"
    }

conn.request("POST", "/v1/projects/{project_id}/keys", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

// .NET

using Deepgram;

var deepgram = new DeepgramClient(new Credentials("YOUR_DEEPGRAM_API_KEY"));
var key = await deepgram.Keys.CreateKeyAsync("DEEPGRAM_PROJECT_ID", "COMMENT", new string[] { "member" });

// Node.js 

const http = require('https')

const options = {
  method: 'POST',
  hostname: 'api.deepgram.com',
  port: null,
  path: '/v1/projects/{project_id}/keys',
  headers: {
    'content-type': 'application/json',
    Authorization: 'Token <YOUR_DEEPGRAM_API_KEY>',
  },
}

const req = http.request(options, function (res) {
  const chunks = []

  res.on('data', function (chunk) {
    chunks.push(chunk)
  })

  res.on('end', function () {
    const body = Buffer.concat(chunks)
    console.log(body.toString())
  })
})

req.write(JSON.stringify({ comment: 'string', scopes: ['string'] }))
req.end()

# PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.deepgram.com/v1/projects/{project_id}/keys",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\"comment\":\"string\",\"scopes\":[\"string\"]}",
  CURLOPT_HTTPHEADER => [
    "Authorization: Token <YOUR_DEEPGRAM_API_KEY>",
    "content-type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

# Ruby

require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://api.deepgram.com/v1/projects/{project_id}/keys")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Post.new(url)
request["content-type"] = 'application/json'
request["Authorization"] = 'Token <YOUR_DEEPGRAM_API_KEY>'
request.body = "{\"comment\":\"string\",\"scopes\":[\"string\"]}"

response = http.request(request)
puts response.read_body

response

{
  "api_key_id": "uuid",
  "key": "string",
  "comment": "string",
  "scopes": [
    "string"
  ],
  "tags": [
    "string"
  ],
  "created": "YYYY-MM-DDThh:mm:ss.sTZD",
  "expiration_date": "YYYY-MM-DDThh:mm:ss.sTZD"
}

Delete Key

Deletes the specified key in the specified project. If the authenticated account has access to the members:write, admins:write, and owners:write project scopes, it will delete any key in the project. Otherwise, it will delete only keys belonging to the authenticated account.

Required account/project scope(s): keys:write. Optional project scope(s): members:write, admins:write, owners:write.

Path Parameters

project_id: uuid

Unique identifier of the project that contains the key that you want to delete.

key_id: uuid

Unique identifier of the key that you want to delete.

Responses

Status	Description
200 Success	Key deleted.

Response Schema

message: string

Message returned. Should read “Successfully deleted the API key!”

endpoint

DELETE /projects/{project_id}/keys/{key_id}

Delete Key

# cURL

curl --request DELETE \
  --url 'https://api.deepgram.com/v1/projects/{project_id}/keys/{key_id}' \
  --header 'Authorization: Token <YOUR_DEEPGRAM_API_KEY>' \
  --header 'content-type: application/json'

# python

import http.client

conn = http.client.HTTPSConnection("api.deepgram.com")

headers = {
    'Authorization': "Token <YOUR_DEEPGRAM_API_KEY>",
    'content-type': "application/json"
    }

conn.request("DELETE", "/v1/projects/{project_id}/keys/{key_id}", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

// .NET

using Deepgram;

var deepgram = new DeepgramClient(new Credentials("YOUR_DEEPGRAM_API_KEY"));
var response = await deepgram.Keys.DeleteKeyAsync("DEEPGRAM_PROJECT_ID", "KEY_ID");

// Node.js

const http = require('https')

const options = {
  method: 'DELETE',
  hostname: 'api.deepgram.com',
  port: null,
  path: '/v1/projects/{project_id}/keys/{key_id}',
  headers: {
    Authorization: 'Token <YOUR_DEEPGRAM_API_KEY>',
    'content-type': 'application/json',
  },
}

const req = http.request(options, function (res) {
  const chunks = []

  res.on('data', function (chunk) {
    chunks.push(chunk)
  })

  res.on('end', function () {
    const body = Buffer.concat(chunks)
    console.log(body.toString())
  })
})

req.end()

# PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.deepgram.com/v1/projects/{project_id}/keys/{key_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "DELETE",
  CURLOPT_HTTPHEADER => [
    "Authorization: Token <YOUR_DEEPGRAM_API_KEY>",
    "content-type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

# Ruby

require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://api.deepgram.com/v1/projects/{project_id}/keys/{key_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Delete.new(url)
request["Authorization"] = 'Token <YOUR_DEEPGRAM_API_KEY>'
request["content-type"] = 'application/json'

response = http.request(request)
puts response.read_body

response

{
  "message": "string"
}

Keys

Get Keys

Path Parameters

Responses

Response Schema

Get Key

Path Parameters

Responses

Response Schema

Create Key

Path Parameters

Request Body Schema

Responses

Response Schema

Delete Key

Path Parameters

Responses

Response Schema

Share your feedback