CONNECT

API keys

An API key is how your student records system, HR system or scripts talk to Peridot. Each key belongs to your organisation and can only see your organisation’s data. Keys start with pk_ and go in the Authorization header of every call.

Create a key

An org admin creates keys while signed in to Peridot, with POST /v1/api-keys and a name that says what the key is for. The answer contains the key itself, once. Copy it into your system’s secret store straight away.

Create a key while signed in as an org admin

POST /v1/api-keys
Content-Type: application/json

{ "name": "Student records sync" }

201 Created
{
  "api_key": { "id": "key_…", "name": "Student records sync", "prefix": "pk_7Hq2" },
  "key": "pk_7Hq2…"
}

Use a key

Send it as a bearer token. PERIDOT below stands for the address you use for Peridot.

Call the API with a key

curl "$PERIDOT/v1/results?course=CSC111&limit=50" \
  -H "Authorization: Bearer pk_7Hq2…"

Revoke a key

DELETE /v1/api-keys/ followed by the key’s id stops it at once. Anything still using it gets refused. List your keys, with their names and the first few characters, with GET /v1/api-keys.

A key's life. Creating and revoking both appear in the audit log.