API Key Endpoints

The API key endpoints are used to view and manage API keys to grant access to the service. They respond and deal with one of the following entities:

Entities

Key Entity

Key entities represent API keys which have access to the service. As JSON they look like this:

{
	// A unique identifier for the key, used in the X-Api-Key header
	"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",

	// When the key was generated
	"generated": "2017-11-06T12:09:43.276Z",

	// A short human-readable description of the key
	"description": "A read key for Origami dashboards",

	// The permissions that this key grants when used to authenticate
	"permissions": {
		"read": true,
		"write": false,
		"admin": false
	}
}

Credentials Entity

Credentials entities represent a full set of credentials (key and secret) which have access to the service. As JSON they look like this:

{
	// A unique identifier for the key, used in the X-Api-Key header
	"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",

	// The secret for the key, used in the X-Api-Secret header
	"secret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
}

Get all API keys

Get a list of all available API keys for this service as an array. This endpoint responds with an array of Key entities. This endpoint requires the ADMIN permission.

Request

Method GET
Path /v1/keys
Headers
X-Api-Key
See authentication docs
X-Api-Secret
See authentication docs

Response

Status 200 on success
401 if authentication failed
403 if authorization failed
Headers
Content-Type
application/json on success
text/html on error
Body Array of Key entities

Example curl command:

curl \
	-H 'X-Api-Key: XXXXXX' -H 'X-Api-Secret: XXXXXX' \
	https://origami-repo-data.ft.com/v1/keys

Get an API key

Get a single API key for this service by ID. This endpoint responds with a Key entity. This endpoint requires the ADMIN permission.

Request

Method GET
Path /v1/keys/:key-id
(where :key-id is the unique identifier for a Key)
Headers
X-Api-Key
See authentication docs
X-Api-Secret
See authentication docs

Response

Status 200 on success
401 if authentication failed
403 if authorization failed
404 if a key matching :key-id does not exist
Headers
Content-Type
application/json on success
text/html on error
Body Key entity

Example curl command:

curl \
	-H 'X-Api-Key: XXXXXX' -H 'X-Api-Secret: XXXXXX' \
	https://origami-repo-data.ft.com/v1/keys/XXXXXX

Create an API key

Create a new API key which can be used to access the service. This endpoint accepts key details and responds with a Credentials entity: the new API key and secret. This endpoint requires the ADMIN permission.

⚠️ The API secret will only ever be output once when the key is created. After this point it is hashed and unreadable even by the service. Be sure to save the output somewhere secure, such as LastPass.

Request

Method POST
Path /v1/keys
Headers
Content-Type
application/json
X-Api-Key
See authentication docs
X-Api-Secret
See authentication docs
Body
{
	// A short human-readable description of the key (required)
	"description": "A read key for Origami dashboards",

	// The permissions that this key grants (optional)
	"read": true,   // defaults to true
	"write": false, // defaults to false
	"admin": false  // defaults to false
}

Response

Status 201 on success
400 if the request data is invalid or malformed
401 if authentication failed
403 if authorization failed
Headers
Content-Type
application/json on success
text/html on error
Body Credentials entity

Example curl command:

curl -X POST \
	-H 'Content-Type: application/json' -H 'X-Api-Key: XXXXXX' -H 'X-Api-Secret: XXXXXX' \
	-d '{"description": "A new API key", "read": true, "write": true, "admin": false}' \
	https://origami-repo-data.ft.com/v1/keys

Delete an API key

Delete a single API key from this service by ID. This endpoint requires the ADMIN permission. Additionally, you are not permitted to delete the same API key that you are currently authenticating with.

Request

Method DELETE
Path /v1/keys/:key-id
(where :key-id is the unique identifier for a Key)
Headers
X-Api-Key
See authentication docs
X-Api-Secret
See authentication docs

Response

Status 204 on success
401 if authentication failed
403 if authorization failed
404 if a key matching :key-id does not exist
Headers
Content-Type
Empty on success
text/html on error
Body Empty

Example curl command:

curl -X DELETE \
	-H 'X-Api-Key: XXXXXX' -H 'X-Api-Secret: XXXXXX' \
	https://origami-repo-data.ft.com/v1/keys/XXXXXX