PATCH/v1/api-keys/{key_id}

Update an API key

update_api_key

Changes the data profile, scopes, collection restriction, allowed networks and expiration of the key. Fields that are not passed stay unchanged.

Authentication

Send an API key in the Authorization header: Authorization: Bearer <key>.

Path parameters

key_idintegerrequired

Header parameters

Idempotency-Keystring
Key for a safe retry of a write: 1 to 255 printable ASCII characters; a UUID v4 per logical operation is recommended. A retry with the same key within 24 hours does not run the operation again: it returns the saved response (status, headers and body) with the Idempotency-Replayed: true header. The same key with a different method, path, Content-Type or body returns 409 api.idempotency_mismatch; while the first request is still running, 409 api.idempotency_in_progress with Retry-After: 1. After a 5xx or 429 response the key is released, and a retry runs the operation again. The key is scoped to the organization and the caller (API key, user, or custom source key).
length ≥ 1, length ≤ 255
X-View-Asstring
For API keys with the admin role only. Makes the request as the data profile <profile>[:viewer|verifier|editor], for example employee:viewer. The installation key cannot use this header (403).

Cookie parameters

kb_view_asstring
Cookie of the “View as” mode for a session. POST /auth/view-as sets it and DELETE /auth/view-as clears it.

Request body

application/json

Object: ApiKeyUpdate

data_profilestring
New data profile of the key. A data profile does not apply to the admin role, so for an admin key a profile other than full returns 400 api_keys.data_profile_not_applicable.
scopesarray of ApiKeyScope
Scopes of the key. The system scope is not issued through the API.
collection_idsarray of integer
Restricts the key to these collections. An empty list means no restriction. A calling key that is itself restricted to collections sees and changes only keys in its collections (other keys return 404 api_keys.not_found) and can set only a non-empty list of its own collections. An empty list or a collection outside its list returns 400 api_keys.invalid_collections. Without this field, the collections of the key stay unchanged.
items ≤ 100
allowed_cidrsarray of string
Networks the key may be used from.
items ≤ 50
expires_atstring (date-time) | null
Expiration time (in the future). null means the key does not expire.

Responses

200OK

Response headers

RateLimit-Policy
Limits in effect, in the format of the IETF draft draft-ietf-httpapi-ratelimit-headers: comma-separated items "<name>";q=<quota>;w=<window in seconds>. key is the request rate of the API key (the quota is the burst, the window is the time to refill it fully; for a session it is user, without credentials ip); minute, day and month are the organization's quotas for the calendar minute, day and month in UTC.
RateLimit
What is left of each limit in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit of the strictest entry in RateLimit-Policy (the one with the fewest requests left).
X-RateLimit-Remaining
Requests left under the strictest limit.
X-RateLimit-Reset
Seconds until the strictest limit resets.
Idempotency-Replayed
true means the response was replayed from the saved one for this Idempotency-Key: the operation did not run again.

application/json

Object: StatusOk

status"ok"required

400The request is invalid: a parameter value or the state of the object does not allow the action (`detail` is a message).

Response headers

RateLimit-Policy
Limits in effect, in the format of the IETF draft draft-ietf-httpapi-ratelimit-headers: comma-separated items "<name>";q=<quota>;w=<window in seconds>. key is the request rate of the API key (the quota is the burst, the window is the time to refill it fully; for a session it is user, without credentials ip); minute, day and month are the organization's quotas for the calendar minute, day and month in UTC.
RateLimit
What is left of each limit in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit of the strictest entry in RateLimit-Policy (the one with the fewest requests left).
X-RateLimit-Remaining
Requests left under the strictest limit.
X-RateLimit-Reset
Seconds until the strictest limit resets.

application/json

Object: Error

401No credentials were sent (neither a session cookie nor an API key), or the key was not found.

Response headers

RateLimit-Policy
Limits in effect, in the format of the IETF draft draft-ietf-httpapi-ratelimit-headers: comma-separated items "<name>";q=<quota>;w=<window in seconds>. key is the request rate of the API key (the quota is the burst, the window is the time to refill it fully; for a session it is user, without credentials ip); minute, day and month are the organization's quotas for the calendar minute, day and month in UTC.
RateLimit
What is left of each limit in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit of the strictest entry in RateLimit-Policy (the one with the fewest requests left).
X-RateLimit-Remaining
Requests left under the strictest limit.
X-RateLimit-Reset
Seconds until the strictest limit resets.

application/json

Object: Error

403The action is not allowed: the role is insufficient, there is no access to the collection or card, the request runs in “View as” mode, or the organization is suspended or deleted (`detail` is an object with `code: org_suspended | org_deleted`).

Response headers

RateLimit-Policy
Limits in effect, in the format of the IETF draft draft-ietf-httpapi-ratelimit-headers: comma-separated items "<name>";q=<quota>;w=<window in seconds>. key is the request rate of the API key (the quota is the burst, the window is the time to refill it fully; for a session it is user, without credentials ip); minute, day and month are the organization's quotas for the calendar minute, day and month in UTC.
RateLimit
What is left of each limit in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit of the strictest entry in RateLimit-Policy (the one with the fewest requests left).
X-RateLimit-Remaining
Requests left under the strictest limit.
X-RateLimit-Reset
Seconds until the strictest limit resets.

application/json

Object: Error

404The object does not exist or is not available to you. The API does not confirm that a restricted object exists.

Response headers

RateLimit-Policy
Limits in effect, in the format of the IETF draft draft-ietf-httpapi-ratelimit-headers: comma-separated items "<name>";q=<quota>;w=<window in seconds>. key is the request rate of the API key (the quota is the burst, the window is the time to refill it fully; for a session it is user, without credentials ip); minute, day and month are the organization's quotas for the calendar minute, day and month in UTC.
RateLimit
What is left of each limit in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit of the strictest entry in RateLimit-Policy (the one with the fewest requests left).
X-RateLimit-Remaining
Requests left under the strictest limit.
X-RateLimit-Reset
Seconds until the strictest limit resets.

application/json

Object: Error

422Validation error: the body or parameters do not match the schema (`detail` is a list of validation errors), or a parameter value is out of range (`detail` is a message).

Response headers

RateLimit-Policy
Limits in effect, in the format of the IETF draft draft-ietf-httpapi-ratelimit-headers: comma-separated items "<name>";q=<quota>;w=<window in seconds>. key is the request rate of the API key (the quota is the burst, the window is the time to refill it fully; for a session it is user, without credentials ip); minute, day and month are the organization's quotas for the calendar minute, day and month in UTC.
RateLimit
What is left of each limit in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit of the strictest entry in RateLimit-Policy (the one with the fewest requests left).
X-RateLimit-Remaining
Requests left under the strictest limit.
X-RateLimit-Reset
Seconds until the strictest limit resets.

application/json

Object: Error

429Too many requests (`api.rate_limited`), the organization's quota for the minute, day or month is used up (`api.quota_exceeded`; `error.details` holds `quota`, `limit` and `reset_at`), the organization's limit is reached, or the answer service is busy (`answers.engine_busy`). Wait for the time in the `Retry-After` header.

Response headers

Retry-After
Number of seconds to wait before you retry the request.
RateLimit-Policy
Limits in effect, in the format of the IETF draft draft-ietf-httpapi-ratelimit-headers: comma-separated items "<name>";q=<quota>;w=<window in seconds>. key is the request rate of the API key (the quota is the burst, the window is the time to refill it fully; for a session it is user, without credentials ip); minute, day and month are the organization's quotas for the calendar minute, day and month in UTC.
RateLimit
What is left of each limit in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limit of the strictest entry in RateLimit-Policy (the one with the fewest requests left).
X-RateLimit-Remaining
Requests left under the strictest limit.
X-RateLimit-Reset
Seconds until the strictest limit resets.

application/json

Object: Error

Error codes

Codes this endpoint can return in error.code, besides the general codes of every request.

Safe retries

Send an Idempotency-Key header (for example a UUID) with each POST and PATCH. A retry with the same key within 24 hours returns the saved response instead of running the request again.

Rate limits

Responses carry the RateLimit and RateLimit-Policy headers and the earlier X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. A 429 response has Retry-After in seconds: wait and retry.

← api-keys · API reference

curl -X PATCH 'https://api.sursa.com/v1/api-keys/1' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"data_profile":"string","scopes":["read"],"collection_ids":[1]}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

Try it

API key

The key stays in the memory of this tab and is sent only to https://api.sursa.com.

Requests act on the real data of your organization.

Idempotency-Key header

X-View-As header

key_id path *

Idempotency-Key

A new key is generated for each request when this is empty.

Request body (JSON)