Skip to content

Make an API key

POST
/v1/keys
curl --request POST \
--url https://api.metaphoric.io/v1/keys \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "name": "example", "scopes": [ "memories:read" ], "user_id": null, "expires_at": null }'

Needs keys:manage. The new key does no more than the key that asks: no scope that key lacks, no other user, and no later expiry. A tenant holds a limited number of working keys, and fewer for any one user.

Media typeapplication/json
object
name
required

Your label for the key: 1 to 64 letters, numbers, punctuation marks or symbols of any script, with single spaces between, in Unicode NFC. A character that draws nothing, such as a zero-width space or a Hangul filler, is refused.

string
>= 1 characters <= 64 characters /^[\p{L}\p{M}\p{N}\p{P}\p{S}]+(?: [\p{L}\p{M}\p{N}\p{P}\p{S}]+)*$/
scopes
required
Array<string>
>= 1 items <= 5 items
Allowed values: memories:read memories:write memories:forget keys:manage users:erase
user_id

The one end user the key may act for: your own ID, 1 to 256 visible ASCII characters but " and \, not starting with metaphor:. Null for a key of your own server.

string | null
>= 1 characters <= 256 characters /^[!#-[\]-~]+$/
not string
/^metaphor:/
expires_at
string | null format: date-time

Example

2027-01-31T09:30:00Z

The key was made.

Media typeapplication/json
object
id
required
string
/^[0-9a-f]{16}$/
name
required
string
scopes
required
Array<string>
Allowed values: memories:read memories:write memories:forget keys:manage users:erase
user_id
required

The one user the key may act for. Null for a key of the tenant’s own server, and for a key whose user was erased.

string | null
held_to_user
required

Whether the key was made for one user. A key whose user was erased is revoked and keeps true here, with user_id null and its name replaced, so nothing of the user’s ID is left in it.

boolean
created_at
required
string format: date-time
expires_at
required

Null for a key that never expires.

string | null format: date-time
revoked_at
required

Null for a key that is not revoked.

string | null format: date-time
last_used_at
required

When the key last passed its check, to within an hour, even if the route’s scopes then refused the request. Null for a key never used.

string | null format: date-time
made_by
required

The ID of the key that made this one. Null for a key Metaphor made for the tenant. Revoking a key does not revoke the keys it made.

string | null
/^[0-9a-f]{16}$/
key
required

The key itself. It is shown once.

string

Example

{
"id": "9f2c4e6a8b0d1f35",
"scopes": [
"memories:read"
],
"created_at": "2027-01-31T09:30:00Z",
"expires_at": "2027-01-31T09:30:00Z",
"revoked_at": "2027-01-31T09:30:00Z",
"last_used_at": "2027-01-31T09:30:00Z",
"made_by": "9f2c4e6a8b0d1f35"
}

The request is not valid.

Media typeapplication/json
object
error
required
object
code
required

One of ErrorCode, or a code added since. Treat a code you do not know by its status.

string
message
required
string

Example generated

{
"error": {
"code": "example",
"message": "example"
}
}

No valid API key was sent.

Media typeapplication/json
object
error
required
object
code
required

One of ErrorCode, or a code added since. Treat a code you do not know by its status.

string
message
required
string

Example generated

{
"error": {
"code": "example",
"message": "example"
}
}

The API key does not allow this.

Media typeapplication/json
object
error
required
object
code
required

One of ErrorCode, or a code added since. Treat a code you do not know by its status.

string
message
required
string

Example generated

{
"error": {
"code": "example",
"message": "example"
}
}

The tenant or the user holds as many working keys as it may. Revoke one first.

Media typeapplication/json
object
error
required
object
code
required

One of ErrorCode, or a code added since. Treat a code you do not know by its status.

string
message
required
string

Example generated

{
"error": {
"code": "example",
"message": "example"
}
}

The request body is too large.

Media typeapplication/json
object
error
required
object
code
required

One of ErrorCode, or a code added since. Treat a code you do not know by its status.

string
message
required
string

Example generated

{
"error": {
"code": "example",
"message": "example"
}
}

The body was not sent as application/json.

Media typeapplication/json
object
error
required
object
code
required

One of ErrorCode, or a code added since. Treat a code you do not know by its status.

string
message
required
string

Example generated

{
"error": {
"code": "example",
"message": "example"
}
}

The API key sent more than 600 requests in a minute, the user’s keys together more than 2000, the tenant’s keys together more than 6000, or the tenant’s keys made as many keys as they may in 24 hours. Wait the seconds Retry-After gives.

Media typeapplication/json
object
error
required
object
code
required

One of ErrorCode, or a code added since. Treat a code you do not know by its status.

string
message
required
string

Example generated

{
"error": {
"code": "example",
"message": "example"
}
}

Something went wrong. Try again.

Media typeapplication/json
object
error
required
object
code
required

One of ErrorCode, or a code added since. Treat a code you do not know by its status.

string
message
required
string

Example generated

{
"error": {
"code": "example",
"message": "example"
}
}

The request could not be checked. Try again.

Media typeapplication/json
object
error
required
object
code
required

One of ErrorCode, or a code added since. Treat a code you do not know by its status.

string
message
required
string

Example generated

{
"error": {
"code": "example",
"message": "example"
}
}