API Key commands: issue, revoke, roll
The API Key Verbs issue, revoke, roll as CLI commands, with inputs, result, refusals and an example.
Reference for API Key, one group of API Key commands.
APIKey.issue
Issue creates an API Key for one Customer and returns its secret once; afterwards only the prefix shows. Verb page.
npx startup-builder do APIKey.issue --json '<input>' [--try | --send | --do]Emits APIKey.issued.
Inputs
| Input | Type | Required | Description |
|---|---|---|---|
customer | Customer | required | The Customer whose calls it signs. |
name | string | required | What the key is for. |
environment | string | required | One of test or live. |
verbs | list of Verb | The Verbs it may call; unset reaches every Verb the Customer’s Entitlements grant. | |
expiresAt | datetime | When it stops working on its own. |
Returns
| Output | Type | Required | Description |
|---|---|---|---|
apiKey | API Key | required | The API Key, with its prefix. |
secret | string | required | The full secret. It is returned here once and never again. |
Refuses when
| Check | Error | Fix | Then call |
|---|---|---|---|
| The key is valid, but its scopes do not allow this operation. | forbidden | Use a key whose scopes cover the operation, or ask an owner of the namespace to grant them. | None. |
Example
npx startup-builder do APIKey.issue --json '{"customer":APIKey.revoke
Revoke stops an API Key at once: its next call fails with 401, and the record and its history stay. Verb page.
npx startup-builder do APIKey.revoke --json '<input>' [--try | --send | --do]Emits APIKey.revoked.
Inputs
| Input | Type | Required | Description |
|---|---|---|---|
apiKey | API Key | required | The API Key to stop. |
reason | text | Why, shown to the Customer’s admins. |
Returns
| Output | Type | Required | Description |
|---|---|---|---|
apiKey | API Key | required | The API Key, with revokedAt set. |
Refuses when
| Check | Error | Fix | Then call |
|---|---|---|---|
| The key is valid, but its scopes do not allow this operation. | forbidden | Use a key whose scopes cover the operation, or ask an owner of the namespace to grant them. | None. |
Example
npx startup-builder do APIKey.revoke --json '{"apiKey":APIKey.roll
Roll issues a replacement API Key with the same scope and keeps the old one working until a set time. Verb page.
npx startup-builder do APIKey.roll --json '<input>' [--try | --send | --do]Emits APIKey.rolled.
Inputs
| Input | Type | Required | Description |
|---|---|---|---|
apiKey | API Key | required | The API Key to replace. |
expireIn | string | How long the old key keeps working, from 0h to 7d. Defaults to 24h. |
Returns
| Output | Type | Required | Description |
|---|---|---|---|
apiKey | API Key | required | The replacement API Key. |
secret | string | required | The replacement’s full secret, returned once. |
Refuses when
| Check | Error | Fix | Then call |
|---|---|---|---|
| The key is valid, but its scopes do not allow this operation. | forbidden | Use a key whose scopes cover the operation, or ask an owner of the namespace to grant them. | None. |
Example
npx startup-builder do APIKey.roll --json '{"apiKey":