Skip to content

Create API key

Request

Create a new API key and return it. The token field is shown only once and cannot be retrieved again — the caller must store it securely.

Security
api_key
Bodyapplication/jsonrequired

The API key to create.

expiresAtstring, (date-time)

Optional expiry timestamp. Omit for a key that does not expire.

namestringrequired
organisationIdstring, (uuid)

Target organisation for the key. Only honoured for callers with the :all scope; org-scoped callers always create within their own organisation. Required when an :all caller has no active organisation (e.g. support users).

rolestringrequired

The role whose permissions the key is granted. The caller may only assign a role they are permitted to grant; assigning admin requires admin-level privileges.

Enum:"admin""manager""member""analyst"
siteIdsArray of strings, (uuid)

Sites the key is scoped to. Required (and must be non-empty) for the site-scoped roles member and analyst; must be omitted for the org-scoped roles admin and manager. Every site must belong to the key's organisation.

curl -i -X POST \
  https://coreapi.hoxton.ai/_mock/v1/api-keys \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "expiresAt": "2019-08-24T14:15:22Z",
    "name": "string",
    "organisationId": "c9b3f279-e3b5-4204-ad99-646257417f98",
    "role": "admin",
    "siteIds": [
      "497f6eca-6276-4993-bfeb-53cbbbba6f08"
    ]
  }'

Responses

Created.

Bodyapplication/json
apiKeystringread-onlyrequired

The full API key, sent as a bearer token in the Authorization header. Returned once at creation and never again.

apiKeyIdstring, (uuid)read-onlyrequired
createdAtstring, (date-time)read-only
expiresAtstring or null, (date-time)
namestringrequired
organisationIdstring, (uuid)read-onlyrequired
prefixstringread-onlyrequired

Public identifier embedded in the API key; also shown in the UI.

rolestringrequired

The role whose permissions the key is granted.

siteIdsArray of strings, (uuid)read-only

Sites the key is scoped to. Populated for member and analyst keys; empty for admin and manager keys.

Response
{
  "apiKey": "string",
  "apiKeyId": "37ba0474-c0bb-4910-bfb5-d6cebb614366",
  "createdAt": "2019-08-24T14:15:22Z",
  "expiresAt": "2019-08-24T14:15:22Z",
  "name": "string",
  "organisationId": "c9b3f279-e3b5-4204-ad99-646257417f98",
  "prefix": "string",
  "role": "string",
  "siteIds": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ]
}