API
Keys
The keys that protect your organization's data, your own keys for encrypting and signing, and your personal keys.
See Keys and secrets. Nothing here returns key material, wrapped or not, or any AWS KMS id: only our own key ids (ck_…) and metadata. keys:read lists and describes every key that protects the organization's data; keys:write rotates, schedules, re-encrypts and manages the organization's own keys; keys:use encrypts, decrypts, signs and verifies with them, and each of those counts towards the plan's monthly key operations. /v1/me/keys shows a person their own keys (Health, their personal Drive and Photos), which no organization sees.
Every route below, with its parameters, request and response, errors and samples, is in the API reference.
| Route | What it does |
|---|---|
GET /v1/orgs/:orgId/keys | Every key that protects the org's data, grouped by app on the page: Drive, secrets, connectors, integrations and the org's own keys (keys:read). With only keys:use, the org's own keys. Also the plan's limits and this month's operations. |
POST /v1/orgs/:orgId/keys | Makes one of the org's own keys (keys:write). |
GET /v1/orgs/:orgId/keys/:keyId | A key: versions still in use, created, rotated, last used, uses in the last 30 days, recent re-encryption jobs. |
GET /v1/orgs/:orgId/keys/:keyId/audit | Who or what used the key, how and when (the org's audit log for this key; keys:read). |
POST /v1/orgs/:orgId/keys/:keyId/rotate | A new version for new data; older versions keep decrypting. reencrypt: also move existing data to it, in the background. |
POST /v1/orgs/:orgId/keys/:keyId/reencrypt | Moves existing data to the current version, in the background (where the app supports it). |
GET /v1/orgs/:orgId/keys/:keyId/jobs/:jobId | A re-encryption job's progress: state, seen, moved, current (already on the newest version), failed and total where known. Needs keys:read. |
PUT /v1/orgs/:orgId/keys/:keyId/schedule | Rotates every rotateEveryDays days from now; null turns the schedule off. |
POST /v1/orgs/:orgId/keys/:keyId/disable | The org's own keys only: nothing seals or opens with a disabled key until it's enabled again. |
POST /v1/orgs/:orgId/keys/:keyId/enable | Turns one of the organization's own keys back on after disable. Needs keys:write. |
DELETE /v1/orgs/:orgId/keys/:keyId | Destroys one of the org's own keys, which must be disabled first: nothing it encrypted can be decrypted again. |
POST /v1/orgs/:orgId/keys/:keyId/encrypt | Encrypts up to 64 KB with an aes-256-gcm key. context: values the ciphertext is bound to; decrypting needs the same. |
POST /v1/orgs/:orgId/keys/:keyId/decrypt | Decrypts a ciphertext (k1.…) made with this key, with the context it was encrypted with, as text (encoding: "utf8", the default) or base64. Any version of the key opens what it sealed. Counts towards the plan's monthly operations and is an audit event. Needs keys:use. |
POST /v1/orgs/:orgId/keys/:keyId/rewrap | The same ciphertext under the key's current version, without the plaintext leaving the service. |
POST /v1/orgs/:orgId/keys/:keyId/sign | Signs up to 64 KB with an ed25519 or ecdsa-p256 key (ECDSA signs the message's SHA-256). |
POST /v1/orgs/:orgId/keys/:keyId/verify | Checks a signature (k1s.…) from sign against message: { valid }. Counts towards the plan's monthly operations. Needs keys:use. |
GET /v1/me/keys | Your personal keys (Health, your own Drive and Photos space) with uses in the last 30 days and when last used. Never key material. Only you see them: people only, not API keys or connected apps. |
GET /v1/me/keys/:keyId | One of your personal keys: versions still in use, created, last rotated, last used, uses in the last 30 days. |
GET /v1/me/keys/:keyId/audit | Your key's uses, from your own audit log (nobody else's log has them). |