Authentication
API keys, the permissions that each key holds, and the permissions of the calling key on objects. Access control describes the permission model.
List API keys
Returns a page of the API keys that the calling key can read, without the secrets. The list supports filters, ordering and cursor or offset pagination, as described in [API conventions](../01-api-conventions.md).
Create an API key
Creates an API key with permissions on object types and returns the new key with a generated secret. Foundation4 returns the secret only in this response and stores only a hash, so a lost secret cannot be recovered. Permissions on individual objects are granted afterward with `POST /api-keys/{api_key_id}/permissions`.
Get an API key
Returns one API key, without the secret.
Update an API key
Changes the name, description, active status or expiration time of an API key. Fields that the request omits keep their values, and `null` removes the description or the expiration time. Deactivation with `'active': false` takes effect on the next request that uses the key.
Delete an API key
Deletes an API key and the key's permission entries. Requests that use the deleted key are refused from the next request. A key cannot delete itself.
List the permissions of an API key
Returns every permission entry of an API key: the entries on object types and the entries on individual objects. An entry on an object type has the object identifier `00000000-0000-0000-0000-000000000000`.
Set the permissions of an API key
Adds, changes or removes permission entries of an API key; entries that the request does not name are unchanged. An entry replaces the entry with the same object type and object identifier, and a permission of 0 removes the entry. Foundation4 applies all entries in one transaction, so a refused entry leaves every entry unchanged.
Check an API key
Checks the API key in the `x-api-key` and `x-api-key-secret` headers and returns the name and description of the key and the key's permissions on object types. The request has no body. The response has status 201, although the operation creates no object.
Get permissions on object types
Returns the permissions of the calling API key on object types, with the classification allow-list of the `pipelines` permission. Permissions on individual objects are not included; `GET /permissions/{object_type}/{object_id}` reports the permission on one object.
Get permissions on several objects
Returns the permissions of the calling API key on several objects of one type, as an object that maps each object identifier to a permission from 0 to 7. The request names each object in a separate `object_id` query parameter, such as `?object_id=<id>&object_id=<id>`. Each permission combines the key's permission on the object type with the key's permission on the object.
Get the permission on an object
Returns the permission of the calling API key on one object, as the sum of the permission bits: read 4, write 2 and execute 1. The value combines the key's permission on the object type with the key's permission on the object.