API Key

The api_key object

An API key used to authenticate requests to the OpenMRP API.

A key always acts on behalf of the account it was created under, with the permissions of the role assigned to it.

idstring

API key ID.

objectstringenumValues:api_key

Resource type identifier.

namestring

Human-readable name for the API key.

redacted_valuestring

Redacted key value safe for display.

The key's prefix followed by its last four characters, e.g. mrp_sk_prod_****hjt4.

rolerolenullable

Role assigned to the key, which determines the permissions of requests made with it.

idstring

Role ID.

objectstringenumValues:role

Resource type identifier.

namestring

Display name of the role.

Unique within the account.

typestringenumValues:adminuserscanner

The kind of role.

The type gates behavior that individual permissions do not cover, and some actions are reserved for a single role type.

  • admin: full administrative access. Sensitive areas such as API keys, billing, and third-party integrations are restricted to admins no matter what permissions another role holds.
  • user: a custom role tailored to a specific need, with its permissions defined explicitly. Roles created through the API always have this type.
  • scanner: the role used by shop-floor scanning stations, assigned automatically when a scanning-station user is created.
  • sales_rep: a role for sales representatives. Order analytics are scoped to the rep's own orders.
  • agent: a role assigned to an automated agent rather than a person.
ownerownernullable

Provenance of this role.

System-owned roles are platform-provided defaults shared across all accounts and cannot be updated or deleted; account-owned roles are custom to your account.

Always returned as null in this endpoint.
permissionsarray of stringnullable

Permissions granted by this role, in {permission}:{action} format, such as customers:read.

created_atstring (date-time)

Creation timestamp.

updated_atstring (date-time)

Last updated timestamp.

last_used_atstring (date-time)nullable

When the key was last used to authenticate a request.

Recorded at most once every 24 hours, so it can lag the key's most recent use by up to a day.

expires_atstring (date-time)nullable

When the key expires and stops authenticating requests.

A key with no expiration keeps working until it is revoked or rotated.

revoked_atstring (date-time)nullable

When the key's revocation takes effect.

A future timestamp means revocation was scheduled (for example, by a rotation) and the key continues to authenticate requests until that time.

created_atstring (date-time)

Creation timestamp.

updated_atstring (date-time)

Last updated timestamp.

Used by

POSTCreate API KeyAPI KeyGETList API KeysAPI KeyGETRetrieve API KeyAPI KeyDELETERevoke API KeyAPI KeyPOSTRotate API KeyAPI Key