Authentication

All /v1/data/* endpoints require a bearer token passed in the Authorization header.

Token format

Tokens follow this format depending on environment:

labs_live_<48-character-hex-string>      # Production
labs_sandbox_<48-character-hex-string>   # Sandbox

Passing the token

Include the token as a bearer value in the Authorization header on every request:

curl https://api.labs.org.za/v1/data/universities \
  -H "Authorization: Bearer labs_live_your_token_here"

Token types

Type	Prefix	Use for
Production	`labs_live_`	Live applications. Counts against your monthly quota.
Sandbox	`labs_sandbox_`	Development and testing. Quota tracked separately; does not affect production limits.

Creating tokens

Go to Dashboard → Tokens and click New token. Give the token a name, select the scopes it needs, and choose production or sandbox.

Important: The raw token value is shown only once immediately after creation. It is stored as a one-way hash and cannot be retrieved again. Copy it to a secure location before closing the page. If lost, delete the token and create a new one.

Error responses

401 UnauthorizedUNAUTHORIZED

The Authorization header is missing, malformed, or the token does not exist.

403 ForbiddenFORBIDDEN

The token is valid but the account is suspended or the token does not have the required scope for this endpoint.

403 ForbiddenSCOPE_REQUIRED

The token exists but lacks the specific scope needed (e.g. universities:read is missing).

Security best practices

Store tokens in environment variables. Never hard-code them in source files.
Never include tokens in client-side JavaScript or public repositories.
Use sandbox tokens during local development so you do not consume production quota.
Grant only the scopes a token actually needs.
Rotate a token immediately if you suspect it has been exposed.