Secret Management API

The Nexmo Secret Management API enables you to create one new API Secret in addition to your existing API Secret. Once you've validated that your new API secret works you can revoke your old API secret using this API

Download OpenAPI 3 Definition

Retrieve API Secrets

GET https://api.nexmo.com/accounts/:api_key/secrets

Authentication

Key Description Example Default
Authorization Base64 encoded API key and secret joined by a colon.
Read more
Basic <base64> None

Path Parameters

Key Description Example Default
api_key
Required | string

The API key to manage secrets for

abcd1234 None

View response field descriptions

Response Fields

Field Description
_embedded

A list of secrets under the "secrets" key. See Retrieve Secret for a description of the returned fields

Field Description
secrets
array of objects
Field Description
id

Secret ID

created_at

The date/time the secret was created

{
  "_links": {
    "self": {
      "href": "/accounts/abcd1234/secrets"
    }
  },
  "_embedded": {
    "secrets": [
      {
        "_links": {
          "self": {
            "href": "/accounts/abcd1234/secrets/ad6dc56f-07b5-46e1-a527-85530e625800"
          }
        },
        "id": "ad6dc56f-07b5-46e1-a527-85530e625800",
        "created_at": "2017-03-02T16:34:49Z"
      }
    ]
  }
}
{
  "type": "https://developer.nexmo.com/api-errors#unauthorized",
  "title": "Invalid credentials supplied",
  "detail": "You did not provide correct credentials.",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.nexmo.com/api-errors#invalid-api-key",
  "title": "Invalid API Key",
  "detail": "API key 'ABC123' does not exist, or you do not have access",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}

Create API Secret

POST https://api.nexmo.com/accounts/:api_key/secrets

Authentication

Key Description Example Default
Authorization Base64 encoded API key and secret joined by a colon.
Read more
Basic <base64> None

Path Parameters

Key Description Example Default
api_key
Required | string

The API key to manage secrets for

abcd1234 None

Request body application/json

Key Description Example Default
secret
Required | string

The new secret must follow these rules:

  • minimum 8 characters
  • maximum 25 characters
  • minimum 1 lower case character
  • minimum 1 upper case character
  • minimum 1 digit
example-4PI-secret None

View response field descriptions

Response Fields

Field Description
id

Secret ID

created_at

The date/time the secret was created

{
  "_links": {
    "self": {
      "href": "/accounts/abcd1234/secrets/ad6dc56f-07b5-46e1-a527-85530e625800"
    }
  },
  "id": "ad6dc56f-07b5-46e1-a527-85530e625800",
  "created_at": "2017-03-02T16:34:49Z"
}
{
  "type": "https://developer.nexmo.com/api-errors/account/secret-management#validation",
  "title": "Bad Request",
  "detail": "The request failed due to validation errors",
  "invalid_parameters": [
    {
      "name": "secret",
      "reason": "Does not meet complexity requirements"
    }
  ],
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.nexmo.com/api-errors#unauthorized",
  "title": "Invalid credentials supplied",
  "detail": "You did not provide correct credentials.",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.nexmo.com/api-errors/account/secret-management#maximum-secrets-allowed",
  "title": "Maxmimum number of secrets already met",
  "detail": "This account has reached maximum number of '2' allowed secrets",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.nexmo.com/api-errors#invalid-api-key",
  "title": "Invalid API Key",
  "detail": "API key 'ABC123' does not exist, or you do not have access",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}

Retrieve API Secret

GET https://api.nexmo.com/accounts/:api_key/secrets/:secret_id

Authentication

Key Description Example Default
Authorization Base64 encoded API key and secret joined by a colon.
Read more
Basic <base64> None

Path Parameters

Key Description Example Default
api_key
Required | string

The API key to manage secrets for

abcd1234 None
secret_id
Required | string

ID of the API Secret

ad6dc56f-07b5-46e1-a527-85530e625800 None

View response field descriptions

Response Fields

Field Description
id

Secret ID

created_at

The date/time the secret was created

{
  "_links": {
    "self": {
      "href": "/accounts/abcd1234/secrets/ad6dc56f-07b5-46e1-a527-85530e625800"
    }
  },
  "id": "ad6dc56f-07b5-46e1-a527-85530e625800",
  "created_at": "2017-03-02T16:34:49Z"
}
{
  "type": "https://developer.nexmo.com/api-errors#unauthorized",
  "title": "Invalid credentials supplied",
  "detail": "You did not provide correct credentials.",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.nexmo.com/api-errors#invalid-api-key",
  "title": "Invalid API Key",
  "detail": "API key 'ABC123' does not exist, or you do not have access",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}

Revoke API Secret

DELETE https://api.nexmo.com/accounts/:api_key/secrets/:secret_id

Authentication

Key Description Example Default
Authorization Base64 encoded API key and secret joined by a colon.
Read more
Basic <base64> None

Path Parameters

Key Description Example Default
api_key
Required | string

The API key to manage secrets for

abcd1234 None
secret_id
Required | string

ID of the API Secret

ad6dc56f-07b5-46e1-a527-85530e625800 None
No content
{
  "type": "https://developer.nexmo.com/api-errors#unauthorized",
  "title": "Invalid credentials supplied",
  "detail": "You did not provide correct credentials.",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}
{
  "type": "https://developer.nexmo.com/api-errors/account/secret-management#delete-last-secret",
  "title": "Secret Deletion Forbidden",
  "detail": "Can not delete the last secret. The account must always have at least 1 secret active at any time",
  "instance": "797a8f199c45014ab7b08bfe9cc1c12c"
}