> Tychron Atlas API & Provisioning Reference — chapter 14 of 35 as Markdown. Web version: https://docs.tychron.com/api-reference/api-keys/
> Source: https://docs.tychron.com/api-reference/ · Updated 2026-08-12 · Generated from the Atlas OpenAPI spec (https://api.atlas.tychron.online/api/v1/openapi is the live contract; this file is a dated snapshot of it).
> Source revision: atlas_api_reference_2026-08-12.md · sha256 482ebd3b014af053 · sanitize gate v1 clean · reconciled with OpenAPI 2026.8.25-p01 (spec sha256 cc049ef38c71cd6e) on 2026-09-05 · content last modified 2026-09-09 · newer definition under review since 2026-09-09 (not yet reconciled)
> Scope: the Atlas platform API only. The SMS, MMS, CNAM, LRN and MCL services are separate APIs with their own specifications: https://docs.tychron.com/openapi/
> Machine index: https://docs.tychron.com/llms.txt

# API Keys

## Schema

An set of authorization details for various APIs

__Type__ Object

| Name             | Type                     | Description                             |
| ---------------- | ------------------------ | --------------------------------------- |
| `active`         | Boolean                  |                                         |
| `id`             | String(format:uuid)      | [Desc. `id`](https://docs.tychron.com/api-reference/api-keys/#desc-196)                 |
| `identity`       | String                   | [Desc. `identity`](https://docs.tychron.com/api-reference/api-keys/#desc-197)           |
| `inserted_at`    | String(format:date-time) | An ISO8601 formatted timestamp          |
| `key`            | String                   | Token used for HTTP APIs                |
| `name`           | String(3..255)           | A friendly name to identify the API Key |
| `notes`          | String(0..65535)         | [Desc. `notes`](https://docs.tychron.com/api-reference/api-keys/#desc-198)              |
| `smpp_system_id` | String                   | [Desc. `smpp_system_id`](https://docs.tychron.com/api-reference/api-keys/#desc-199)     |
| `updated_at`     | String(format:date-time) | An ISO8601 formatted timestamp          |

#### Desc. `id` {#desc-196}

A Universally unique identifier, which identifies the resource

#### Desc. `identity` {#desc-197}

Acts as the username in the authorization pair for MM4

#### Desc. `notes` {#desc-198}

Any notes about the API Key, like, what it is used for, or other sharable details.

#### Desc. `smpp_system_id` {#desc-199}

Small identifier used when authorizing an SMPP connection



__Example__

```json
{
  "active": true,
  "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
  "identity": "Z46IWURJGLH5SF3BKKZPXW53TAON6NBX",
  "inserted_at": "2021-08-13T04:08:44.762841Z",
  "key": "RBAARJAXGMRJ3AOD55WDO5WKN5GEFZGSZOAGJ27DOYJ22IBRU7W77Z6QKAYXCAXI",
  "name": "My API Key",
  "notes": "This API Key is used for the west datacenter's SMS notifications.",
  "smpp_system_id": "EIIGBT24ZH242U5",
  "updated_at": "2021-08-13T04:08:44.762841Z"
}
```


## Summary

API Keys are your credentials for doing any form of transaction or requests with the system.

API Keys are used for:

* LRN
* CNAM
* MCL
* SMS
  * SMPP
  * HTTP
* MMS
  * MM4
  * HTTP
* All other Atlas API (e.g. GET /api/v1/switches)

While API Keys are a single record, there are two types.

### Standard API Key?

A standard API Key, as covered in [Your Resources](https://docs.tychron.com/api-reference/your-resources/#your-resources), is used to access messaging (i.e. SMS, MMS) and informational services (i.e. LRN, CNAM, MCL).

Standard keys can be made either through the self-service portal, or via the API from an allowed Impersonated API Key.

Standard keys cannot be used to perform ordering, or any of the functions not mentioned.

### Impersonated API Key?

An Impersonated API Key, or user attached API Key is one used to perform extended API operations, it can also be used for messaging and informational services as well.

The API Key will act on behalf of a user present in the system, which also makes the API Key subject to the same permissions and restrictions as the actual user.

This also means that if a user is suspended, the API Key's extended functions will also be suspended.

Messaging and informational services will continue to work as intended.

Impersonated keys cannot be created normally, and require action from support.

You will normally receive an impersonated key on initial account setup.

If you require an additional impersonated key, or wish to further isolate your services, please contact support.

## Where are my secrets?

Upon creating an API Key you should receive the key with all of its secrets generated.

However, subsequent requests to retrieve the key will not return the secrets, the secrets cannot be covered, even by support.

If SMPP, or MM4 access is needed, and the secrets from the API Key are lost, a new one will need to be created.

All dids and switches will need to be re-assigned to the new API Key, where applicable.

## API

### Create API Key

__Data__

| Name     | Type    | Description                           |
| -------- | ------- | ------------------------------------- |
| `active` | Boolean | Whether the API Key is active for use |
| `name`   | String  | A display name for the API Key        |
| `notes`  | String  | Any notes on the API Key              |



```http
POST /api/v1/api_keys HTTP/1.1
```

Create a new API Key.

Note that newly created API Keys will return their secrets, however all subsequent GET requests
will not contain the secrets.


#### Request application/json

```http
POST /api/v1/api_keys HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 105
```

```json
{
  "data": {
    "active": false,
    "name": "string",
    "notes": "string"
  },
  "type": "api_key"
}
```

#### Response 201

##### application/json

```http
HTTP/1.1 201
Content-Type: application/json
Content-Length: 569
```

```json
{
  "data": {
    "active": true,
    "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
    "identity": "Z46IWURJGLH5SF3BKKZPXW53TAON6NBX",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "key": "RBAARJAXGMRJ3AOD55WDO5WKN5GEFZGSZOAGJ27DOYJ22IBRU7W77Z6QKAYXCAXI",
    "name": "My API Key",
    "notes": "This API Key is used for the west datacenter's SMS notifications.",
    "secret": "Z46IWURJGLH5SF3BKKZPXW53TAON6NBX",
    "smpp_secert": "FDJX6MO4",
    "smpp_system_id": "EIIGBT24ZH242U5",
    "updated_at": "2021-08-13T04:08:44.762841Z"
  },
  "type": "api_key"
}
```
#### Response 403

##### application/json

```http
HTTP/1.1 403
Content-Type: application/json
Content-Length: 312
```

```json
{
  "errors": [
    {
      "code": "access_denied.no_scope",
      "detail": "No scope available to user role",
      "params": {
        "action": "index",
        "level": "guest",
        "resource": "resource"
      },
      "sub_code": "none",
      "title": "Access Denied, no scope available"
    }
  ]
}
```
#### Response 404

##### application/json

```http
HTTP/1.1 404
Content-Type: application/json
Content-Length: 241
```

```json
{
  "errors": [
    {
      "code": "invalid_parameter",
      "detail": "The specified resource could not be found",
      "source": {
        "pointer": "/data/type"
      },
      "sub_code": "none",
      "title": "Not Found"
    }
  ]
}
```


### Update API Key

__Data__

| Name     | Type    | Description                           |
| -------- | ------- | ------------------------------------- |
| `active` | Boolean | Whether the API Key is active for use |
| `name`   | String  | A display name for the API Key        |
| `notes`  | String  | Any notes on the API Key              |



```http
PATCH /api/v1/api_keys/{id} HTTP/1.1
```

Update an existing API Key


__Path Parameters__

| Name | Type                 | Description |
| ---- | -------------------- | ----------- |
| id   | String(format:uuid)! | API Key ID  |

#### Request application/json

```http
PATCH /api/v1/api_keys/{id} HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 105
```

```json
{
  "data": {
    "active": false,
    "name": "string",
    "notes": "string"
  },
  "type": "api_key"
}
```

#### Response 200

##### application/json

```http
HTTP/1.1 200
Content-Type: application/json
Content-Length: 488
```

```json
{
  "data": {
    "active": true,
    "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
    "identity": "Z46IWURJGLH5SF3BKKZPXW53TAON6NBX",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "key": "RBAARJAXGMRJ3AOD55WDO5WKN5GEFZGSZOAGJ27DOYJ22IBRU7W77Z6QKAYXCAXI",
    "name": "My API Key",
    "notes": "This API Key is used for the west datacenter's SMS notifications.",
    "smpp_system_id": "EIIGBT24ZH242U5",
    "updated_at": "2021-08-13T04:08:44.762841Z"
  },
  "type": "api_key"
}
```
#### Response 403

##### application/json

```http
HTTP/1.1 403
Content-Type: application/json
Content-Length: 312
```

```json
{
  "errors": [
    {
      "code": "access_denied.no_scope",
      "detail": "No scope available to user role",
      "params": {
        "action": "index",
        "level": "guest",
        "resource": "resource"
      },
      "sub_code": "none",
      "title": "Access Denied, no scope available"
    }
  ]
}
```
#### Response 404

##### application/json

```http
HTTP/1.1 404
Content-Type: application/json
Content-Length: 241
```

```json
{
  "errors": [
    {
      "code": "invalid_parameter",
      "detail": "The specified resource could not be found",
      "source": {
        "pointer": "/data/type"
      },
      "sub_code": "none",
      "title": "Not Found"
    }
  ]
}
```


### Delete API Key

```http
DELETE /api/v1/api_keys/{id} HTTP/1.1
```

Delete an API Key.

Note that an API Key cannot be deleted if it is still associated with any switches or numbers.


__Path Parameters__

| Name | Type                 | Description |
| ---- | -------------------- | ----------- |
| id   | String(format:uuid)! | API Key ID  |

#### Request

```http
DELETE /api/v1/api_keys/{id} HTTP/1.1
Accept: application/json
```
#### Response 200

##### application/json

```http
HTTP/1.1 200
Content-Type: application/json
Content-Length: 488
```

```json
{
  "data": {
    "active": true,
    "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
    "identity": "Z46IWURJGLH5SF3BKKZPXW53TAON6NBX",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "key": "RBAARJAXGMRJ3AOD55WDO5WKN5GEFZGSZOAGJ27DOYJ22IBRU7W77Z6QKAYXCAXI",
    "name": "My API Key",
    "notes": "This API Key is used for the west datacenter's SMS notifications.",
    "smpp_system_id": "EIIGBT24ZH242U5",
    "updated_at": "2021-08-13T04:08:44.762841Z"
  },
  "type": "api_key"
}
```
#### Response 403

##### application/json

```http
HTTP/1.1 403
Content-Type: application/json
Content-Length: 312
```

```json
{
  "errors": [
    {
      "code": "access_denied.no_scope",
      "detail": "No scope available to user role",
      "params": {
        "action": "index",
        "level": "guest",
        "resource": "resource"
      },
      "sub_code": "none",
      "title": "Access Denied, no scope available"
    }
  ]
}
```
#### Response 404

##### application/json

```http
HTTP/1.1 404
Content-Type: application/json
Content-Length: 241
```

```json
{
  "errors": [
    {
      "code": "invalid_parameter",
      "detail": "The specified resource could not be found",
      "source": {
        "pointer": "/data/type"
      },
      "sub_code": "none",
      "title": "Not Found"
    }
  ]
}
```


### List API Keys

```http
GET /api/v1/api_keys HTTP/1.1
```

Retrieve API Keys allocated for this account.


__Query Parameters__

| Name   | Type    | Description                     |
| ------ | ------- | ------------------------------- |
| first  | Integer | [Query Desc. first](https://docs.tychron.com/api-reference/api-keys/#desc-200)  |
| last   | Integer | [Query Desc. last](https://docs.tychron.com/api-reference/api-keys/#desc-201)   |
| after  | String  | [Query Desc. after](https://docs.tychron.com/api-reference/api-keys/#desc-202)  |
| before | String  | [Query Desc. before](https://docs.tychron.com/api-reference/api-keys/#desc-203) |

#### Query Desc. first {#desc-200}

The number of items to return starting from the 'after' cursor

#### Query Desc. last {#desc-201}

The number of items to return behind the 'before' cursor

#### Query Desc. after {#desc-202}

The cursor representing the starting point of a 'first' based paging

#### Query Desc. before {#desc-203}

The cursor representing the starting point of a 'last' based paging

#### Request

```http
GET /api/v1/api_keys HTTP/1.1
Accept: application/json
```
#### Response 200

##### application/json

```http
HTTP/1.1 200
Content-Type: application/json
Content-Length: 705
```

```json
{
  "count": 1,
  "page_info": {
    "first": "string",
    "has_next_page": true,
    "has_previous_page": true,
    "last": "string"
  },
  "results": [
    {
      "data": {
        "active": true,
        "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
        "identity": "Z46IWURJGLH5SF3BKKZPXW53TAON6NBX",
        "inserted_at": "2021-08-13T04:08:44.762841Z",
        "key": "RBAARJAXGMRJ3AOD55WDO5WKN5GEFZGSZOAGJ27DOYJ22IBRU7W77Z6QKAYXCAXI",
        "name": "My API Key",
        "notes": "This API Key is used for the west datacenter's SMS notifications.",
        "smpp_system_id": "EIIGBT24ZH242U5",
        "updated_at": "2021-08-13T04:08:44.762841Z"
      },
      "type": "api_key"
    }
  ]
}
```
#### Response 403

##### application/json

```http
HTTP/1.1 403
Content-Type: application/json
Content-Length: 312
```

```json
{
  "errors": [
    {
      "code": "access_denied.no_scope",
      "detail": "No scope available to user role",
      "params": {
        "action": "index",
        "level": "guest",
        "resource": "resource"
      },
      "sub_code": "none",
      "title": "Access Denied, no scope available"
    }
  ]
}
```


### Get API Key

```http
GET /api/v1/api_keys/{id} HTTP/1.1
```

Lookup an API Key by its ID


__Path Parameters__

| Name | Type                 | Description |
| ---- | -------------------- | ----------- |
| id   | String(format:uuid)! | API Key ID  |

#### Request

```http
GET /api/v1/api_keys/{id} HTTP/1.1
Accept: application/json
```
#### Response 200

##### application/json

```http
HTTP/1.1 200
Content-Type: application/json
Content-Length: 488
```

```json
{
  "data": {
    "active": true,
    "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
    "identity": "Z46IWURJGLH5SF3BKKZPXW53TAON6NBX",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "key": "RBAARJAXGMRJ3AOD55WDO5WKN5GEFZGSZOAGJ27DOYJ22IBRU7W77Z6QKAYXCAXI",
    "name": "My API Key",
    "notes": "This API Key is used for the west datacenter's SMS notifications.",
    "smpp_system_id": "EIIGBT24ZH242U5",
    "updated_at": "2021-08-13T04:08:44.762841Z"
  },
  "type": "api_key"
}
```
#### Response 403

##### application/json

```http
HTTP/1.1 403
Content-Type: application/json
Content-Length: 312
```

```json
{
  "errors": [
    {
      "code": "access_denied.no_scope",
      "detail": "No scope available to user role",
      "params": {
        "action": "index",
        "level": "guest",
        "resource": "resource"
      },
      "sub_code": "none",
      "title": "Access Denied, no scope available"
    }
  ]
}
```
#### Response 404

##### application/json

```http
HTTP/1.1 404
Content-Type: application/json
Content-Length: 314
```

```json
{
  "errors": [
    {
      "code": "not_found",
      "detail": "The specified resource could not be found",
      "params": {
        "resource": {
          "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69",
          "type": "user"
        }
      },
      "sub_code": "none",
      "title": "Not Found"
    }
  ]
}
```


### Bind API Key to DID

```http
POST /api/v1/numbers/{number_id}/api_keys/{api_key_id}/bind HTTP/1.1
```

Bind specified API Key to the number


__Path Parameters__

| Name       | Type                 | Description                        |
| ---------- | -------------------- | ---------------------------------- |
| number_id  | String!              | Number or ID                       |
| api_key_id | String(format:uuid)! | [Path Desc. api_key_id](https://docs.tychron.com/api-reference/api-keys/#desc-204) |

#### Path Desc. api_key_id {#desc-204}

API Key ID A Universally unique identifier, which identifies the resource

#### Request

```http
POST /api/v1/numbers/{number_id}/api_keys/{api_key_id}/bind HTTP/1.1
Accept: application/json
```
#### Response 200

##### application/json

```http
HTTP/1.1 200
Content-Type: application/json
Content-Length: 488
```

```json
{
  "data": {
    "active": true,
    "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
    "identity": "Z46IWURJGLH5SF3BKKZPXW53TAON6NBX",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "key": "RBAARJAXGMRJ3AOD55WDO5WKN5GEFZGSZOAGJ27DOYJ22IBRU7W77Z6QKAYXCAXI",
    "name": "My API Key",
    "notes": "This API Key is used for the west datacenter's SMS notifications.",
    "smpp_system_id": "EIIGBT24ZH242U5",
    "updated_at": "2021-08-13T04:08:44.762841Z"
  },
  "type": "api_key"
}
```
#### Response 403

##### application/json

```http
HTTP/1.1 403
Content-Type: application/json
Content-Length: 312
```

```json
{
  "errors": [
    {
      "code": "access_denied.no_scope",
      "detail": "No scope available to user role",
      "params": {
        "action": "index",
        "level": "guest",
        "resource": "resource"
      },
      "sub_code": "none",
      "title": "Access Denied, no scope available"
    }
  ]
}
```
#### Response 404

##### application/json

```http
HTTP/1.1 404
Content-Type: application/json
Content-Length: 314
```

```json
{
  "errors": [
    {
      "code": "not_found",
      "detail": "The specified resource could not be found",
      "params": {
        "resource": {
          "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69",
          "type": "user"
        }
      },
      "sub_code": "none",
      "title": "Not Found"
    }
  ]
}
```


### Unbind API Key from DID

```http
DELETE /api/v1/numbers/{number_id}/api_keys/{api_key_id}/bind HTTP/1.1
```

Unbind specified API Key from the number


__Path Parameters__

| Name       | Type                 | Description                        |
| ---------- | -------------------- | ---------------------------------- |
| number_id  | String!              | Number or ID                       |
| api_key_id | String(format:uuid)! | [Path Desc. api_key_id](https://docs.tychron.com/api-reference/api-keys/#desc-205) |

#### Path Desc. api_key_id {#desc-205}

API Key ID A Universally unique identifier, which identifies the resource

#### Request

```http
DELETE /api/v1/numbers/{number_id}/api_keys/{api_key_id}/bind HTTP/1.1
Accept: application/json
```
#### Response 200

##### application/json

```http
HTTP/1.1 200
Content-Type: application/json
Content-Length: 488
```

```json
{
  "data": {
    "active": true,
    "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
    "identity": "Z46IWURJGLH5SF3BKKZPXW53TAON6NBX",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "key": "RBAARJAXGMRJ3AOD55WDO5WKN5GEFZGSZOAGJ27DOYJ22IBRU7W77Z6QKAYXCAXI",
    "name": "My API Key",
    "notes": "This API Key is used for the west datacenter's SMS notifications.",
    "smpp_system_id": "EIIGBT24ZH242U5",
    "updated_at": "2021-08-13T04:08:44.762841Z"
  },
  "type": "api_key"
}
```
#### Response 403

##### application/json

```http
HTTP/1.1 403
Content-Type: application/json
Content-Length: 312
```

```json
{
  "errors": [
    {
      "code": "access_denied.no_scope",
      "detail": "No scope available to user role",
      "params": {
        "action": "index",
        "level": "guest",
        "resource": "resource"
      },
      "sub_code": "none",
      "title": "Access Denied, no scope available"
    }
  ]
}
```
#### Response 404

##### application/json

```http
HTTP/1.1 404
Content-Type: application/json
Content-Length: 314
```

```json
{
  "errors": [
    {
      "code": "not_found",
      "detail": "The specified resource could not be found",
      "params": {
        "resource": {
          "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69",
          "type": "user"
        }
      },
      "sub_code": "none",
      "title": "Not Found"
    }
  ]
}
```

---

Previous chapter: https://docs.tychron.com/api-reference/users.md  
Next chapter: https://docs.tychron.com/api-reference/bulk-dip-tasks.md  
Complete reference in one file: https://docs.tychron.com/llms-full.txt