Skip to main content
Unkey Deploy is currently in private beta. To get access, reach out on Discord or email support@unkey.com.
When the Principal’s type is "key", the source.key object contains the full details of the verified API key. This page documents every field in the API key source.

​
Fields

​
source.key.keyId
string
required
The ID of the API key that authenticated the request. When the key is linked to an identity, the top-level subject is the identity’s external ID, so use this field when you need to identify the specific key that was used (for example, for key-level analytics or revocation).
​
source.key.keySpaceId
string
required
The ID of the keyspace the key belongs to. Useful when your Sentinel is configured with multiple keyspaces and your application needs to distinguish which keyspace matched.
​
source.key.name
string
The human-readable name of the key, if one was set when the key was created. Absent when the key has no name. Useful for displaying which key was used in dashboards or audit logs (for example, “ACME Production Key”).
​
source.key.expiresAt
integer
Unix timestamp (seconds) when the key expires. Absent when the key has no expiry. The Sentinel already rejects expired keys, so if this field is present the key is still valid. Your application can use it to warn users about upcoming expiration.
​
source.key.meta
object
required
Custom key-value metadata attached to the key. This is the same metadata you set through the Unkey API when creating or updating the key. Use it to pass per-key attributes to your application, for example an environment label or a customer tier. Empty {} when no metadata is set.
​
source.key.roles
string[]
required
The roles attached to the key, as flat string identifiers (for example, ["admin", "billing"]). Empty [] when no roles are attached. These are the raw role names from Unkey, available for your application’s own authorization logic.
​
source.key.permissions
string[]
required
The permissions attached to the key, as flat string identifiers (for example, ["api.read", "api.write"]). Empty [] when no permissions are attached.These are the raw permissions from Unkey. If the Sentinel enforced a permission query and the key lacked the required permissions, the request was already rejected before reaching your app. The permissions here let your application make additional fine-grained authorization decisions beyond what the Sentinel enforces.

​
Examples

{
  "version": 1,
  "subject": "key_3xMpL9kF2nR",
  "type": "key",
  "source": {
    "key": {
      "keyId": "key_3xMpL9kF2nR",
      "keySpaceId": "ks_abc123",
      "name": "ACME Production Key",
      "expiresAt": 1717200000,
      "meta": {
        "environment": "production"
      },
      "roles": ["admin", "billing"],
      "permissions": ["api.read", "api.write", "billing.manage"]
    }
  }
}
Last modified on March 30, 2026