Skip to content

Create Api Key

POST
/api-keys

Mint a new API key for the caller’s own org. The token is returned exactly once.

Authorizations

Parameters

Header Parameters

X-Target-Org-Id
Any of:
string

Request Body required

Request to mint a new organization API key.

extra="forbid" so a caller sending org_id, is_agency or is_ops gets an explicit 422 instead of the field being silently dropped — it is a stronger, more debuggable signal that those fields do not exist on this door.

object
environment
Any of:
string
Allowed values: live sandbox
expires_in_days
Any of:
integer
>= 1 <= 365
ip_allowlist

Optional list of IPv4/IPv6 CIDR strings (e.g. [‘10.0.0.0/8’, ‘2001:db8::/32’]). Bare IPs are accepted as /32 (IPv4) or /128 (IPv6). When non-empty, only requests from a matching IP are accepted — all others receive 403. Empty list (the default) means unrestricted: the key works from any IP address. Maximum 50 entries.

Array<string>
mode

Key mode. A ‘test’ key is returned with a g8_test_ prefix; a ‘live’ key carries g8_live_; a ‘sandbox’ key carries g8_sbx_ and only authenticates against the graph8 developer sandbox. A key minted by a ‘test’-mode credential is always forced to ‘test’ regardless of this field — a test key may not mint itself a live successor.

string
default: live
Allowed values: live test sandbox
name
required

Human-readable name for the key

string
>= 1 characters <= 100 characters
scopes
Any of:
Array<string>

Responses

201

Successful Response

object
data
required

Response after minting a key.

api_key_token is returned exactly once, here, at creation. No other endpoint on this router — or the app’s — ever returns it again.

object
api_key_id
required
string
api_key_token
required
string
environment

Sandbox or live, derived from mode (additive; a test key reads live).

string
default: live
mode
string
default: live
name
required
string
scopes
Array<string>
pagination
Any of:
object
has_next
required

Whether there are more pages

boolean
limit
required

Items per page

integer
next_cursor
Any of:
string
notes
Any of:
Array<string>
page
required

Current page number (1-indexed)

integer
total
required

Total number of items

integer
total_available
Any of:
integer
total_is_lower_bound
Any of:
boolean

422

Validation Error

object
detail
Array<object>
object
loc
required
Array
msg
required
string
type
required
string