Skip to main content
POST
Create API key

Authorizations

Authorization
string
header
required

First-party Gumnut app session (Clerk session JWT). Only the Gumnut web and mobile apps can obtain one — API keys and OAuth tokens cannot manage credentials, so these operations are not callable with the credentials this API otherwise accepts.

Body

application/json

Create a key with an explicit action/library scope.

The scope fields are required: a request must state both which actions the key may perform and which libraries it covers; omitting either is a 422, never a silent full-access grant. Full access is still expressible, but only explicitly: actions=[read, write, delete, delete_permanently] plus library_scope_mode=all_libraries.

name
string
required

Descriptive name identifying this API key

Maximum string length: 255
actions
enum<string>[]
required

Action verbs the key may perform (at least one). read is required whenever any broader action is selected. Pass all four actions for a full-access key.

Actions a credential may perform.

read views resources; write creates or changes them; delete trashes photos or libraries and destructively removes organizational records and associations such as albums, people, faces, and memberships; delete_permanently irreversibly deletes photos or libraries.

Available options:
read,
write,
delete,
delete_permanently
library_scope_mode
enum<string>
required

Which libraries the key covers: all_libraries (all current and future libraries) or selected_libraries.

Available options:
all_libraries,
selected_libraries
library_ids
string[] | null

Libraries the key covers. Required (at least one) when library_scope_mode is selected_libraries; not allowed otherwise. Up to 200 ids.

Maximum array length: 200

Response

Successful Response

Response when creating a new API key - includes the actual key value.

This is the only time the raw API key is exposed. After creation, only the hashed version is stored and the raw key cannot be retrieved.

id
string
required

Unique API key identifier with 'apikey_' prefix

created_at
string<date-time>
required

When this API key was created

is_active
boolean
required

Whether this API key is currently valid and can be used

api_key
string
required

The actual API key value - store this securely as it cannot be retrieved later

name
string | null

Optional descriptive name for this API key

last_used_at
string<date-time> | null

When this API key was last used for authentication

actions
enum<string>[] | null

Action verbs this key's grant allows; null for legacy keys

Actions a credential may perform.

read views resources; write creates or changes them; delete trashes photos or libraries and destructively removes organizational records and associations such as albums, people, faces, and memberships; delete_permanently irreversibly deletes photos or libraries.

Available options:
read,
write,
delete,
delete_permanently
library_scope_mode
enum<string> | null

'all_libraries' or 'selected_libraries'; null for legacy keys

Available options:
all_libraries,
selected_libraries
selected_library_count
integer | null

Number of libraries a 'selected_libraries' grant covers; null unless library_scope_mode is 'selected_libraries'