Create a permission

POST /v1/permissions · permission apis:write

Adds a permission (OAuth scope) to an API, optionally with the texts shown on the consent screen. Supports Idempotency-Key.

Request

Field Type Required Description
api_id string yes The API (api_…).
value string yes Scope value, resource:action (^[a-z0-9_.-]{1,64}:[a-z0-9_.*-]{1,64}$). Unique within the API and unchangeable. The idp_ prefix is reserved.
display_name string | null no Short name shown on the consent screen instead of the scope value. At most 128 characters.
description string | null no Detail line shown under the name on the consent screen. At most 1024 characters.
consent_text_i18n object | null no Language tag → consent screen text, for example {"en": "Read your orders"}. At most 30 languages, each text 1-1024 characters, 16 KiB in total.
sensitivity string no normal (default) or sensitive.

The hosted consent screen shows each requested scope as follows: the consent_text_i18n entry for the page language (exact tag, otherwise its primary subtag), otherwise display_name, otherwise the scope value; description is shown as a detail line. All three are plain text. Control characters (including line breaks and tabs), line and paragraph separators and bidirectional embedding, override and isolate characters (U+202A-U+202E, U+2066-U+2069) are rejected with 422. Leading and trailing whitespace is trimmed, and a text that is empty after trimming is stored as null. HTML is not interpreted: the consent screen escapes it.

Response

201 Created

{
  "id": "perm_01h455vb4pex5vsknk084sn02s",
  "api_id": "api_01h455vb4pex5vsknk084sn02q",
  "value": "read:orders",
  "display_name": "Read orders",
  "description": "See your past orders and their status",
  "consent_text_i18n": {
    "en": "Read your orders",
    "tr": "Siparişlerinizi okuyun"
  },
  "sensitivity": "normal"
}

Errors

HTTP code When
400 unknown_field The body contains an unknown field.
403 insufficient_permissions The credential lacks apis:write.
403 quota_exceeded The API already has 1,000 permissions.
404 not_found There is no such API in this environment.
409 conflict The value already exists on this API, or the API is the system API.
422 validation_failed A field is missing or invalid, or a text is not plain text (errors[].pointer names the field, for example /consent_text_i18n).

Example

curl -X POST https://api.eu.keenauth.com/v1/permissions \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1d2c1e-perm-create" \
  -d '{"api_id":"api_01h455vb4pex5vsknk084sn02q","value":"read:orders","display_name":"Read orders","consent_text_i18n":{"en":"Read your orders"}}'

With the CLI, pass the language map with --data:

echo '{"consent_text_i18n":{"en":"Read your orders"}}' | keenauth permissions create \
  --api-id api_01h455vb4pex5vsknk084sn02q --value read:orders --display-name "Read orders" --data -