Peeker Partner API

Every request needs a bearer key. Create live (pk_live_…) and sandbox (pk_test_…) keys in the Partner portal. Sandbox orders do not bill or run live fulfillment.

Get a key

Open the Partner portal

Go to Partner → API.

Create a key

Choose New key, add a label, and pick a permission preset. Copy the secret now. You will not see it again.

Pick the environment

pk_live_… is production. pk_test_… is sandbox. Both use the same base URL: https://api.peeker.ai/partner/v1.

Send the key on every request

curl https://api.peeker.ai/partner/v1/me \
  -H "Authorization: Bearer pk_test_<your-key>"

Use exactly Authorization: Bearer <key>. No other auth schemes are accepted.

Verify with `GET /me`

This is the cheapest health check. It confirms the key, environment, and preset.

curl https://api.peeker.ai/partner/v1/me \
  -H "Authorization: Bearer pk_test_<your-key>"

{
	"data": {
		"api_key": {
			"environment": "test",
			"permission_preset": "full"
		},
		"partner": {
			"id": "org_01HZX0OG1A2B3C4D5E6F7G8H",
			"name": "Acme Resellers"
		}
	}
}

A 200 with api_key.environment: "test" means you are on sandbox routes.

Permission presets

Presets are locked at creation. They show up on GET /me as api_key.permission_preset.

Preset	Reads	Writes
`full`	All resources	Everything
`limited`	All resources	Domain availability only. No other writes.
`read`	All resources	None. Writes return `403 forbidden`.

To change a preset, create a new key and revoke the old one.

Rotate without downtime

Create the replacement

Partner portal → API → New key. It is valid immediately.

Roll your deployment

Ship the new key. Both keys work during rollout.

Revoke the old key

Revocation is immediate. Requests that still use the old key return 401 unauthorized.

Revoke immediately if a key leaks. There is no soft-revoke window.

Track requests with `Peeker-Request-Id`

Every response includes Peeker-Request-Id (an opaque UUID). Log it. Support looks it up when you contact us. Errors also include the same value as error.request_id.

HTTP/1.1 200 OK
Peeker-Request-Id: 550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json

Unauthorized and forbidden

`401 unauthorized`

Missing, malformed, or revoked key:

{
	"error": {
		"code": "unauthorized",
		"message": "Invalid API key",
		"request_id": "550e8400-e29b-41d4-a716-446655440000"
	}
}

`403 forbidden`

Valid key without permission for that action. Use a full key for most writes, or limited for availability only.

{
	"error": {
		"code": "forbidden",
		"message": "API key does not have permission for order_create",
		"request_id": "550e8400-e29b-41d4-a716-446655440000"
	}
}

Concepts

Authentication

Get a key

Send the key on every request

Verify with `GET /me`

Permission presets

Rotate without downtime

Track requests with `Peeker-Request-Id`

Unauthorized and forbidden

`401 unauthorized`

`403 forbidden`

​Get a key

​Send the key on every request

​Verify with GET /me

​Permission presets

​Rotate without downtime

​Track requests with Peeker-Request-Id

​Unauthorized and forbidden

​401 unauthorized

​403 forbidden

Get a key

Send the key on every request

Verify with `GET /me`

Permission presets

Rotate without downtime

Track requests with `Peeker-Request-Id`

Unauthorized and forbidden

`401 unauthorized`

`403 forbidden`