API Key

A record that represents an access token for use with various APIs and messaging channels.

Note: The API key provided in the Authorization header must have the apik_ prefix.

Schema

Name	Type	Description
id	ULID	Unique identifier
inserted_at	String(format:datetime)	Creation timestamp
name	String(1..64)	The display name of the API Key
notes	String	Any additional notes about the API Key
smpp_secret	String(8..8)	The SMPP secret, only available upon creation of a new API Key
smpp_system_id	String(15..15)	The SMPP System ID associated with this API Key. Please note, SMS queues are bound to the smpp_system_id
token	String(32..64)	Primary HTTP Authorization token, it shall be used with the Bearer scheme. Example: Authorization: Bearer API_KEY_TOKEN
updated_at	String(format:datetime)	Last update timestamp

Examples

Create API Key

Creates an API key for the immediate account.

Request:

POST https://api.swift-api.com/api/v1/api_keys HTTP/1.1
Accept: application/json, text/plain
Content-Type: application/json
Content-Length: 64
Authorization: Bearer apik_ABC123

{
  "data": {
    "name": "string",
    "notes": "This API Key will be used for the Westcoast SMS Application.\n"
  },
  "type": "api_key"
}

Response:

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

{
  "data": {
    "id": "01J0CRVTXX9KBD9NWS02R5R8RT",
    "inserted_at": "2024-06-14T00:00:00.000000Z",
    "name": "string",
    "notes": "This API Key will be used for the Westcoast SMS Application.\n",
    "smpp_secret": "PASSWORD",
    "smpp_system_id": "ABCDEF123456789",
    "token": "string",
    "updated_at": "2024-06-14T00:00:00.000000Z"
  },
  "type": "api_key"
}

Create API Key for Account

Create a new API key under the specified account.

Request:

POST https://api.swift-api.com/api/v1/accounts/{account_id}/api_keys HTTP/1.1
Accept: application/json, text/plain
Content-Type: application/json
Content-Length: 64
Authorization: Bearer apik_ABC123
{
  "data": {
    "name": "string",
    "notes": "This API Key will be used for the Westcoast SMS Application.\n"
  },
  "type": "api_key"
}

Response:

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

{
  "data": {
    "id": "01J0CRVTXX9KBD9NWS02R5R8RT",
    "inserted_at": "2024-06-14T00:00:00.000000Z",
    "name": "string",
    "notes": "This API Key will be used for the Westcoast SMS Application.\n",
    "smpp_secret": "PASSWORD",
    "smpp_system_id": "ABCDEF123456789",
    "token": "string",
    "updated_at": "2024-06-14T00:00:00.000000Z"
  },
  "type": "api_key"
}

List API Keys

List all API Keys from immediate and sub accounts.

Request:

GET https://api.swift-api.com/api/v1/api_keys HTTP/1.1
Accept: application/json, text/plain
Authorization: Bearer apik_ABC123

Response:

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

{
  "data": {
    "items": [
      {
        "data": {
          "id": "01J0CRVTXX9KBD9NWS02R5R8RT",
          "inserted_at": "2024-06-14T00:00:00.000000Z",
          "name": "string",
          "notes": "This API Key will be used for the Westcoast SMS Application.\n",
          "smpp_secret": "PASSWORD",
          "smpp_system_id": "ABCDEF123456789",
          "token": "string",
          "updated_at": "2024-06-14T00:00:00.000000Z"
        },
        "type": "api_key"
      }
    ],
    "page_info": {
      "after": "string",
      "before": "string",
      "limit": 0.0,
      "total": 0.0
    }
  },
  "type": "list"
}

Get API Key

Retrieve an API key by ID.

Request:

GET https://api.swift-api.com/api/v1/api_keys/{id} HTTP/1.1
Accept: application/json, text/plain
Authorization: Bearer apik_ABC123

Response:

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

{
  "data": {
    "id": "01J0CRVTXX9KBD9NWS02R5R8RT",
    "inserted_at": "2024-06-14T00:00:00.000000Z",
    "name": "string",
    "notes": "This API Key will be used for the Westcoast SMS Application.\n",
    "smpp_secret": "PASSWORD",
    "smpp_system_id": "ABCDEF123456789",
    "token": "string",
    "updated_at": "2024-06-14T00:00:00.000000Z"
  },
  "type": "api_key"
}

Get impersonated user for account key

Gets the user object for the given API key.

Request:

GET /api/v1/api_keys/{api_key_id}/impersonated_user HTTP/1.1
Accept: application/json, text/plain

Success response:

HTTP/1.1 200
Content-Type: application/json
Content-Length: 287
{
  "data": {
    "email": "[email protected]",
    "first_name": "John",
    "id": "01J0CRVTXX9KBD9NWS02R5R8RT",
    "inserted_at": "2024-06-14T00:00:00.000000Z",
    "last_name": "Doe",
    "name": "ACME User",
    "updated_at": "2024-06-14T00:00:00.000000Z"
    },
  "type": "user"
}

Unauthorized response:

HTTP/1.1 403
Content-Type: application/json
Content-Length: 262
{
"errors": [
  {
    "code": "access_denied.no_scope",
    "detail": "string",
    "params": {
      "action": "create",
      "level": "string",
      "resource": "accounts"
    },
    "sub_code": "none",
    "title": "string"
    }
  ]
}

Set API Key’s impersonated user

Set a user to an API Key to enhance its capabilities. It is strongly recommended to assign a role to the user with as few permissions as necessary.

Request:

PUT https://api.swift-api.com/api/v1/api_keys/{api_key_id}/impersonated_user/{id} HTTP/1.1
Accept: application/json, text/plain

Success response:

HTTP/1.1 200
Content-Type: application/json
Content-Length: 287
{
  "data": {
    "email": "[email protected]",
    "first_name": "John",
    "id": "01J0CRVTXX9KBD9NWS02R5R8RT",
    "inserted_at": "2024-06-14T00:00:00.000000Z",
    "last_name": "Doe",
    "name": "ACME User",
    "updated_at": "2024-06-14T00:00:00.000000Z"
  },
  "type": "user"
}

Unauthorized response:

HTTP/1.1 403
Content-Type: application/json
Content-Length: 262
{
  "errors": [
    {
      "code": "access_denied.no_scope",
      "detail": "string",
      "params": {
        "action": "create",
        "level": "string",
        "resource": "accounts"
      },
      "sub_code": "none",
      "title": "string"
    }
  ]
}

Remove API Key’s impersonated user

Unsets the user an API key is impersonating.

Request:

DELETE https://api.swift-api.com/api/v1/api_keys/{api_key_id}/impersonated_user HTTP/1.1
Accept: text/plain, application/json

Success response:

HTTP/1.1 204

Unauthorized response:

HTTP/1.1 403
Content-Type: application/json
Content-Length: 262
{
  "errors": [
    {
      "code": "access_denied.no_scope",
      "detail": "string",
      "params": {
        "action": "create",
        "level": "string",
        "resource": "accounts"
      },
      "sub_code": "none",
      "title": "string"
    }
  ]
}