API Keys V1

API key operations

List all API keys

Returns a list of your API keys. Results are paginated to improve retrieval peformance. The meta data indicates how many total records exist.

SecuritybasicAuth or bearerAuth
Request
query Parameters
include_permission_groups
boolean

If false, only ids will be returned, otherwise the nested resources will be returned.

page[number]
number <double>

Current page based on pagination settings.

page[size]
number <double>

Number of results to return per page based on pagination settings.

Responses
200

Successful response

Response Schema: application/json
Array of objects (API Key)
object (Metadata)
401

Authentication error

Response Schema: application/json
Array of objects (Error Base)
Array
code
string

an application-specific error code, expressed as a stringified integer.

title
string

a short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization. Do not include punctuation in the title.

detail
string

a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.

pointer
string

JSON pointer to the field which is causing the error.

403

Authorization error

Response Schema: application/json
Array of objects (Error Base)
Array
code
string

an application-specific error code, expressed as a stringified integer.

title
string

a short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization. Do not include punctuation in the title.

detail
string

a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.

pointer
string

JSON pointer to the field which is causing the error.

422

Invalid parameters supplied in request. See HTTP response body for details.

Response Schema: application/json
Array of objects (Error Base)
Array
code
string

an application-specific error code, expressed as a stringified integer.

title
string

a short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization. Do not include punctuation in the title.

detail
string

a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.

pointer
string

JSON pointer to the field which is causing the error.

get/auth/api_keys
Request samples 
Response samples 
application/json
{
  • "data": [
    • {
      • "id": "f30e7596-586e-44e1-ae7d-53db10f144d3",
      • "description": "Tommy's Key",
      • "secret": "XXXXXXXXXXXXX",
      • "backup_secret": "XXXXXXXXXXXXX",
      • "status": "active",
      • "permission_groups": [
        • "string"
        ],
      • "admin": true,
      • "record_type": "api_key",
      • "created_at": "2018-02-08T18:49:22.998023Z",
      • "updated_at": "2018-02-08T18:49:22.998023Z"
      }
    ],
  • "meta": {
    • "total_pages": 13,
    • "total_results": 13,
    • "page_number": 3,
    • "page_size": 1
    }
}
Create an API key
Creates a new API key object.


SecuritybasicAuth or bearerAuth 
Request 
Request Body schema: application/json
required
description
required
string
Human readable identifier.


 
permission_groups
required
Array of strings
Array of ids of Permission Groups on the API Key.


 
admin
required
boolean
True if the API Key has admin rights, false otherwise.


 
Responses 
200
Successful response


Response Schema: application/json
object (API Key) 
 
id
string
uuid.


 
description
string
Human readable identifier.


 
secret
string
Secret used to authenticate API Key.


 
backup_secret
string
Secondary secret which may also be used to authenticate API Key.


 
status
string
Status of the API Key.


 
permission_groups
Array of strings
Array of ids of Permission Groups on the API Key.


 
admin
boolean
True if the API Key has admin rights, false otherwise.


 
record_type
string
Record type.


 
created_at
string
Timestamp of resource creation.


 
updated_at
string
Timestamp of last resource update.


 
401
Authentication error


Response Schema: application/json
Array of objects (Error Base) 
 
 Array 
code
string
an application-specific error code, expressed as a stringified integer.


 
title
string
a short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization. Do not include punctuation in the title.


 
detail
string
a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.


 
pointer
string
JSON pointer to the field which is causing the error.


 
403
Authorization error


Response Schema: application/json
Array of objects (Error Base) 
 
 Array 
code
string
an application-specific error code, expressed as a stringified integer.


 
title
string
a short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization. Do not include punctuation in the title.


 
detail
string
a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.


 
pointer
string
JSON pointer to the field which is causing the error.


 
422
Invalid parameters supplied in request. See HTTP response body for details.


Response Schema: application/json
Array of objects (Error Base) 
 
 Array 
code
string
an application-specific error code, expressed as a stringified integer.


 
title
string
a short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization. Do not include punctuation in the title.


 
detail
string
a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.


 
pointer
string
JSON pointer to the field which is causing the error.


 
post/auth/api_keys
Request samples 
application/json
{
  • "description": "Tommy's Key",
  • "permission_groups": [
    • "string"
    ],
  • "admin": true
}
Response samples 
application/json
{
  • "data": {
    • "id": "f30e7596-586e-44e1-ae7d-53db10f144d3",
    • "description": "Tommy's Key",
    • "secret": "XXXXXXXXXXXXX",
    • "backup_secret": "XXXXXXXXXXXXX",
    • "status": "active",
    • "permission_groups": [
      • "string"
      ],
    • "admin": true,
    • "record_type": "api_key",
    • "created_at": "2018-02-08T18:49:22.998023Z",
    • "updated_at": "2018-02-08T18:49:22.998023Z"
    }
}
Retrieve an API key
Retrieves the details of an existing API key.


SecuritybasicAuth or bearerAuth 
Request 
path Parameters
id
required
string
The id of the API Key


 
query Parameters
include_permission_groups
boolean
If false, only ids will be returned, otherwise the nested resources will be returned.


 
Responses 
200
Successful response


Response Schema: application/json
object (API Key) 
 
id
string
uuid.


 
description
string
Human readable identifier.


 
secret
string
Secret used to authenticate API Key.


 
backup_secret
string
Secondary secret which may also be used to authenticate API Key.


 
status
string
Status of the API Key.


 
permission_groups
Array of strings
Array of ids of Permission Groups on the API Key.


 
admin
boolean
True if the API Key has admin rights, false otherwise.


 
record_type
string
Record type.


 
created_at
string
Timestamp of resource creation.


 
updated_at
string
Timestamp of last resource update.


 
401
Authentication error


Response Schema: application/json
Array of objects (Error Base) 
 
 Array 
code
string
an application-specific error code, expressed as a stringified integer.


 
title
string
a short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization. Do not include punctuation in the title.


 
detail
string
a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.


 
pointer
string
JSON pointer to the field which is causing the error.


 
403
Authorization error


Response Schema: application/json
Array of objects (Error Base) 
 
 Array 
code
string
an application-specific error code, expressed as a stringified integer.


 
title
string
a short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization. Do not include punctuation in the title.


 
detail
string
a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.


 
pointer
string
JSON pointer to the field which is causing the error.


 
404
Resource not found


Response Schema: application/json
Array of objects (Error Base) 
 
 Array 
code
string
an application-specific error code, expressed as a stringified integer.


 
title
string
a short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization. Do not include punctuation in the title.


 
detail
string
a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.


 
pointer
string
JSON pointer to the field which is causing the error.


 
get/auth/api_keys/{id}
Request samples 
Response samples 
application/json
{
  • "data": {
    • "id": "f30e7596-586e-44e1-ae7d-53db10f144d3",
    • "description": "Tommy's Key",
    • "secret": "XXXXXXXXXXXXX",
    • "backup_secret": "XXXXXXXXXXXXX",
    • "status": "active",
    • "permission_groups": [
      • "string"
      ],
    • "admin": true,
    • "record_type": "api_key",
    • "created_at": "2018-02-08T18:49:22.998023Z",
    • "updated_at": "2018-02-08T18:49:22.998023Z"
    }
}
Update an API key
Updates the specified API key with the values of the parameters passed. Any parameters not included in the request will be left unchanged.


SecuritybasicAuth or bearerAuth 
Request 
path Parameters
id
required
string
The id of the API Key


 
Request Body schema: application/json
required
description
string
Human readable identifier.


 
permission_groups
Array of strings
Array of ids of Permission Groups on the API Key.


 
status
string
Status of the API Key.


 
Responses 
200
Successful response


Response Schema: application/json
object (API Key) 
 
id
string
uuid.


 
description
string
Human readable identifier.


 
secret
string
Secret used to authenticate API Key.


 
backup_secret
string
Secondary secret which may also be used to authenticate API Key.


 
status
string
Status of the API Key.


 
permission_groups
Array of strings
Array of ids of Permission Groups on the API Key.


 
admin
boolean
True if the API Key has admin rights, false otherwise.


 
record_type
string
Record type.


 
created_at
string
Timestamp of resource creation.


 
updated_at
string
Timestamp of last resource update.


 
401
Authentication error


Response Schema: application/json
Array of objects (Error Base) 
 
 Array 
code
string
an application-specific error code, expressed as a stringified integer.


 
title
string
a short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization. Do not include punctuation in the title.


 
detail
string
a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.


 
pointer
string
JSON pointer to the field which is causing the error.


 
403
Authorization error


Response Schema: application/json
Array of objects (Error Base) 
 
 Array 
code
string
an application-specific error code, expressed as a stringified integer.


 
title
string
a short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization. Do not include punctuation in the title.


 
detail
string
a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.


 
pointer
string
JSON pointer to the field which is causing the error.


 
404
Resource not found


Response Schema: application/json
Array of objects (Error Base) 
 
 Array 
code
string
an application-specific error code, expressed as a stringified integer.


 
title
string
a short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization. Do not include punctuation in the title.


 
detail
string
a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.


 
pointer
string
JSON pointer to the field which is causing the error.


 
422
Invalid parameters supplied in request. See HTTP response body for details.


Response Schema: application/json
Array of objects (Error Base) 
 
 Array 
code
string
an application-specific error code, expressed as a stringified integer.


 
title
string
a short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization. Do not include punctuation in the title.


 
detail
string
a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.


 
pointer
string
JSON pointer to the field which is causing the error.


 
patch/auth/api_keys/{id}
Request samples 
application/json
{
  • "description": "Tommy's Key",
  • "permission_groups": [
    • "string"
    ],
  • "status": "active"
}
Response samples 
application/json
{
  • "data": {
    • "id": "f30e7596-586e-44e1-ae7d-53db10f144d3",
    • "description": "Tommy's Key",
    • "secret": "XXXXXXXXXXXXX",
    • "backup_secret": "XXXXXXXXXXXXX",
    • "status": "active",
    • "permission_groups": [
      • "string"
      ],
    • "admin": true,
    • "record_type": "api_key",
    • "created_at": "2018-02-08T18:49:22.998023Z",
    • "updated_at": "2018-02-08T18:49:22.998023Z"
    }
}
Generate an API key's backup secret
Generates a new backup secret for an API key.


SecuritybasicAuth or bearerAuth 
Request 
path Parameters
id
required
string
The id of the API Key


 
Responses 
200
Successful response


Response Schema: application/json
object (API Key) 
 
id
string
uuid.


 
description
string
Human readable identifier.


 
secret
string
Secret used to authenticate API Key.


 
backup_secret
string
Secondary secret which may also be used to authenticate API Key.


 
status
string
Status of the API Key.


 
permission_groups
Array of strings
Array of ids of Permission Groups on the API Key.


 
admin
boolean
True if the API Key has admin rights, false otherwise.


 
record_type
string
Record type.


 
created_at
string
Timestamp of resource creation.


 
updated_at
string
Timestamp of last resource update.


 
401
Authentication error


Response Schema: application/json
Array of objects (Error Base) 
 
 Array 
code
string
an application-specific error code, expressed as a stringified integer.


 
title
string
a short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization. Do not include punctuation in the title.


 
detail
string
a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.


 
pointer
string
JSON pointer to the field which is causing the error.


 
403
Authorization error


Response Schema: application/json
Array of objects (Error Base) 
 
 Array 
code
string
an application-specific error code, expressed as a stringified integer.


 
title
string
a short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization. Do not include punctuation in the title.


 
detail
string
a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.


 
pointer
string
JSON pointer to the field which is causing the error.


 
404
Resource not found


Response Schema: application/json
Array of objects (Error Base) 
 
 Array 
code
string
an application-specific error code, expressed as a stringified integer.


 
title
string
a short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization. Do not include punctuation in the title.


 
detail
string
a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.


 
pointer
string
JSON pointer to the field which is causing the error.


 
post/auth/api_keys/{id}/backup_secret
Request samples 
Response samples 
application/json
{
  • "data": {
    • "id": "f30e7596-586e-44e1-ae7d-53db10f144d3",
    • "description": "Tommy's Key",
    • "secret": "XXXXXXXXXXXXX",
    • "backup_secret": "XXXXXXXXXXXXX",
    • "status": "active",
    • "permission_groups": [
      • "string"
      ],
    • "admin": true,
    • "record_type": "api_key",
    • "created_at": "2018-02-08T18:49:22.998023Z",
    • "updated_at": "2018-02-08T18:49:22.998023Z"
    }
}
Rotate an API key's secret
Replaces an API key's secret with the backup secret. If no backup secret is set, the secret will be replaced with a newly generated value.


SecuritybasicAuth or bearerAuth 
Request 
path Parameters
id
required
string
The id of the API Key


 
Responses 
200
Successful response


Response Schema: application/json
object (API Key) 
 
id
string
uuid.


 
description
string
Human readable identifier.


 
secret
string
Secret used to authenticate API Key.


 
backup_secret
string
Secondary secret which may also be used to authenticate API Key.


 
status
string
Status of the API Key.


 
permission_groups
Array of strings
Array of ids of Permission Groups on the API Key.


 
admin
boolean
True if the API Key has admin rights, false otherwise.


 
record_type
string
Record type.


 
created_at
string
Timestamp of resource creation.


 
updated_at
string
Timestamp of last resource update.


 
401
Authentication error


Response Schema: application/json
Array of objects (Error Base) 
 
 Array 
code
string
an application-specific error code, expressed as a stringified integer.


 
title
string
a short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization. Do not include punctuation in the title.


 
detail
string
a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.


 
pointer
string
JSON pointer to the field which is causing the error.


 
403
Authorization error


Response Schema: application/json
Array of objects (Error Base) 
 
 Array 
code
string
an application-specific error code, expressed as a stringified integer.


 
title
string
a short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization. Do not include punctuation in the title.


 
detail
string
a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.


 
pointer
string
JSON pointer to the field which is causing the error.


 
404
Resource not found


Response Schema: application/json
Array of objects (Error Base) 
 
 Array 
code
string
an application-specific error code, expressed as a stringified integer.


 
title
string
a short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization. Do not include punctuation in the title.


 
detail
string
a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.


 
pointer
string
JSON pointer to the field which is causing the error.


 
post/auth/api_keys/{id}/rotate_secret
Request samples 
Response samples 
application/json
{
  • "data": {
    • "id": "f30e7596-586e-44e1-ae7d-53db10f144d3",
    • "description": "Tommy's Key",
    • "secret": "XXXXXXXXXXXXX",
    • "backup_secret": "XXXXXXXXXXXXX",
    • "status": "active",
    • "permission_groups": [
      • "string"
      ],
    • "admin": true,
    • "record_type": "api_key",
    • "created_at": "2018-02-08T18:49:22.998023Z",
    • "updated_at": "2018-02-08T18:49:22.998023Z"
    }
}
Assign an API key to another user
Assigns an API key to a user. This controls what they are authorized to do in Mission Control.


SecuritybasicAuth or bearerAuth 
Request 
path Parameters
id
required
string
The id of the API Key


 
Request Body schema: application/json
required
user_id
string
uuid for User.


 
Responses 
200
Successful response


Response Schema: application/json
object (API Key) 
 
id
string
uuid.


 
description
string
Human readable identifier.


 
secret
string
Secret used to authenticate API Key.


 
backup_secret
string
Secondary secret which may also be used to authenticate API Key.


 
status
string
Status of the API Key.


 
permission_groups
Array of strings
Array of ids of Permission Groups on the API Key.


 
admin
boolean
True if the API Key has admin rights, false otherwise.


 
record_type
string
Record type.


 
created_at
string
Timestamp of resource creation.


 
updated_at
string
Timestamp of last resource update.


 
401
Authentication error


Response Schema: application/json
Array of objects (Error Base) 
 
 Array 
code
string
an application-specific error code, expressed as a stringified integer.


 
title
string
a short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization. Do not include punctuation in the title.


 
detail
string
a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.


 
pointer
string
JSON pointer to the field which is causing the error.


 
403
Authorization error


Response Schema: application/json
Array of objects (Error Base) 
 
 Array 
code
string
an application-specific error code, expressed as a stringified integer.


 
title
string
a short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization. Do not include punctuation in the title.


 
detail
string
a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.


 
pointer
string
JSON pointer to the field which is causing the error.


 
404
Resource not found


Response Schema: application/json
Array of objects (Error Base) 
 
 Array 
code
string
an application-specific error code, expressed as a stringified integer.


 
title
string
a short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization. Do not include punctuation in the title.


 
detail
string
a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.


 
pointer
string
JSON pointer to the field which is causing the error.


 
422
Invalid parameters supplied in request. See HTTP response body for details.


Response Schema: application/json
Array of objects (Error Base) 
 
 Array 
code
string
an application-specific error code, expressed as a stringified integer.


 
title
string
a short, human-readable summary of the problem that SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization. Do not include punctuation in the title.


 
detail
string
a human-readable explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.


 
pointer
string
JSON pointer to the field which is causing the error.


 
post/auth/api_keys/{id}/assignment
Request samples 
application/json
{
  • "user_id": "e74e0c5c-b185-4e40-8b4a-aae7fc8a9f1d"
}
Response samples 
application/json
{
  • "data": {
    • "id": "f30e7596-586e-44e1-ae7d-53db10f144d3",
    • "description": "Tommy's Key",
    • "secret": "XXXXXXXXXXXXX",
    • "backup_secret": "XXXXXXXXXXXXX",
    • "status": "active",
    • "permission_groups": [
      • "string"
      ],
    • "admin": true,
    • "record_type": "api_key",
    • "created_at": "2018-02-08T18:49:22.998023Z",
    • "updated_at": "2018-02-08T18:49:22.998023Z"
    }
}