API Key programs: issue, revoke, roll

Reference for API Key, one group of API Key programs.

APIKey.issue

Issue creates an API Key for one Customer and returns its secret once; afterwards only the prefix shows. Verb page.

Text

do: return await $.APIKey.issue(input)

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

JSON

{
  "name": "do",
  "arguments": {
    "code": "return await $.APIKey.issue({ customer: 'cus_wjAFWuKWIV', name: 'Nightly sync', environment: 'test' })"
  }
}

APIKey.revoke

Revoke stops an API Key at once: its next call fails with 401, and the record and its history stay. Verb page.

Text

do: return await $.APIKey.revoke(input)

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

JSON

{
  "name": "do",
  "arguments": {
    "code": "return await $.APIKey.revoke({ apiKey: 'key_BG13nfhe26' })"
  }
}

APIKey.roll

Roll issues a replacement API Key with the same scope and keeps the old one working until a set time. Verb page.

Text

do: return await $.APIKey.roll(input)

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

JSON

{
  "name": "do",
  "arguments": {
    "code": "return await $.APIKey.roll({ apiKey: 'key_BG13nfhe26' })"
  }
}

APIKey.issueCopy Anchor Link

APIKey.revokeCopy Anchor Link

APIKey.rollCopy Anchor Link

APIKey.issue

APIKey.revoke

APIKey.roll