v1/api_keys

Use the v1/api_keys API to create, list, and delete API keys that are used to authenticate when calling APIs. For information on using an API key to authenticate see API Keys.

URI

https://<hostname>/ws/v1/api_keys

Formats

No fields are required when creating an API key. A description is recommended and an optional lifetime in seconds can specified (defaults to 365 days).

{
    "description": "key for xyz",
    "lifetime": 31536000
}

The response to the create request will include the secret which must be securely stored as it will never be returned again:

{
	"id": "fbfdaacc8436875ed2b7136bdf3e64e5",
	"customer_id": 2,
	"secret": "fb137da612d892d8802e04b12ae819c73325b8f437988e82fd236eead2e6bca4",
	"username": "someuser",
	"description": "key for xyz",
	"expires": "2025-04-19T20:11:51.673Z",
	"created": "2024-04-19T20:11:51.844Z"
}

A typical API key entry looks like the following:

{
	"id": "f16034671e479552fc7c1721c6639d7c",
	"customer_id": 2,
	"username": "someuser",
	"description": "key for xyz",
	"expires": "2025-04-19T19:31:57.530Z",
	"created": "2024-04-19T19:31:57.623Z",
	"last_used": "2024-04-19T19:33:26.110Z"
}

API Key Data

Each API key has an id, the user the key is for and some metadata relating to its lifetime and usage. The fields are displayed below.

• id - The unique identifier for the key. Read-only, generated by the system.
• customer_id - The unique identifier for the customer account. Read-only, generated by the system.
• username - The name of the user that owns this key. Read-only, determined by the user that created the key.
• description - User supplied description for the key.
• expires - The time that the key will expire. Attempts to authenticate using the key after this time will fail. Read-only, generated by the system.
• created - The time that the key was created. Read-only, generated by the system.
• last_used - The time that the key was last used to successfully authenticate. There may be a short delay in this field updating after a successful authentication. This can be useful to when determining if a key is actively being used. Read-only, generated by the system.
• secret - The secret for the key. Returned only when the key is created. Read-only, generated by the system.
• lifetime - Number of seconds before this key expires. Only accepted when the key is created. Defaults to 31536000 (365 days).