API Keys

Schema

An set of authorization details for various APIs

Type Object

Name	Type	Description
`active`	Boolean
`id`	String(format:uuid)	Desc. `id`
`identity`	String	Desc. `identity`
`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`
`smpp_system_id`	String	Desc. `smpp_system_id`
`updated_at`	String(format:date-time)	An ISO8601 formatted timestamp

Desc. `id`

A Universally unique identifier, which identifies the resource

Desc. `identity`

Acts as the username in the authorization pair for MM4

Desc. `notes`

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

Desc. `smpp_system_id`

Small identifier used when authorizing an SMPP connection

Example

{
  "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, 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

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

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

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

Response 201

application/json

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

{
  "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/1.1 403
Content-Type: application/json
Content-Length: 312

{
  "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/1.1 404
Content-Type: application/json
Content-Length: 241

{
  "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

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

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

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

Response 200

application/json

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

{
  "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/1.1 403
Content-Type: application/json
Content-Length: 312

{
  "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/1.1 404
Content-Type: application/json
Content-Length: 241

{
  "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

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

DELETE /api/v1/api_keys/{id} HTTP/1.1
Accept: application/json

Response 200

application/json

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

{
  "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/1.1 403
Content-Type: application/json
Content-Length: 312

{
  "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/1.1 404
Content-Type: application/json
Content-Length: 241

{
  "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

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
last	Integer	Query Desc. last
after	String	Query Desc. after
before	String	Query Desc. before

Query Desc. first

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

Query Desc. last

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

Query Desc. after

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

Query Desc. before

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

Request

GET /api/v1/api_keys HTTP/1.1
Accept: application/json

Response 200

application/json

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

{
  "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/1.1 403
Content-Type: application/json
Content-Length: 312

{
  "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

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

GET /api/v1/api_keys/{id} HTTP/1.1
Accept: application/json

Response 200

application/json

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

{
  "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/1.1 403
Content-Type: application/json
Content-Length: 312

{
  "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/1.1 404
Content-Type: application/json
Content-Length: 314

{
  "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

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

Path Desc. api_key_id

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

Request

POST /api/v1/numbers/{number_id}/api_keys/{api_key_id}/bind HTTP/1.1
Accept: application/json

Response 200

application/json

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

{
  "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/1.1 403
Content-Type: application/json
Content-Length: 312

{
  "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/1.1 404
Content-Type: application/json
Content-Length: 314

{
  "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

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

Path Desc. api_key_id

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

Request

DELETE /api/v1/numbers/{number_id}/api_keys/{api_key_id}/bind HTTP/1.1
Accept: application/json

Response 200

application/json

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

{
  "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/1.1 403
Content-Type: application/json
Content-Length: 312

{
  "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/1.1 404
Content-Type: application/json
Content-Length: 314

{
  "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"
    }
  ]
}

API Keys

Schema

Desc. id

Desc. identity

Desc. notes

Desc. smpp_system_id

Summary

Standard API Key?

Impersonated API Key?

Where are my secrets?

API

Create API Key

Request application/json

Response 201

application/json

Response 403

application/json

Response 404

application/json

Update API Key

Request application/json

Response 200

application/json

Response 403

application/json

Response 404

application/json

Delete API Key

Request

Response 200

application/json

Response 403

application/json

Response 404

application/json

List API Keys

Query Desc. first

Query Desc. last

Query Desc. after

Query Desc. before

Request

Response 200

application/json

Response 403

application/json

Get API Key

Request

Response 200

application/json

Response 403

application/json

Response 404

application/json

Bind API Key to DID

Path Desc. api_key_id

Request

Response 200

application/json

Response 403

application/json

Response 404

application/json

Unbind API Key from DID

Path Desc. api_key_id

Request

Response 200

application/json

Response 403

application/json

Response 404

application/json

Desc. `id`

Desc. `identity`

Desc. `notes`

Desc. `smpp_system_id`