Managing API Keys

Base URL (local): https://api.gis.ph

All endpoints below are mounted under /v1.

Authentication

These endpoints require an Authorization header:

Authorization: Bearer <token>

Recommended token type for key management:

• Dashboard Supabase JWT (user is logged in via Supabase Auth)

Other accepted token types:

• User API keys (gis_sk_*) are also accepted by the /v1/* auth middleware.
• Master token (APIKEY) is accepted but does not identify a user, so it cannot be used to create/list per-user keys.

---

Response Shape

Most endpoints respond with:

{
  "data": ...,
  "error": null
}

On errors, you may receive:

{ "message": "..." }

---

API Keys

List Your Keys

GET /v1/api-keys

List API keys belonging to the authenticated user.

curl -s "https://api.gis.ph/v1/api-keys" \
  -H "Authorization: Bearer <SUPABASE_JWT_OR_API_KEY>"

Note: This endpoint never returns plaintext keys.

---

Create a Key

POST /v1/api-keys

Create a new API key for the authenticated user.

Payload

{
  "name": "Production key",
  "description": "Used by the public map frontend",
  "environment": "live",
  "expires_at": null,
  "scopes": ["read:boundaries", "read:datasets"],
  "rate_limit_rpm": 120,
  "rate_limit_burst": 60
}

Enforcement (high level):

• scopes — checked on each request for gis_sk_* keys. Null/empty scopes = full access. Missing scope → 403. Vocabulary includes read|write:boundaries|datasets|places|politics|orgs and admin.
• rate_limit_rpm — enforced (null → platform default 60/minute). Over limit → 429. Master token / dashboard JWT are not limited this way.
• Field-level contract: Scalar API reference (tag API Keys).

curl example

curl -s -X POST "https://api.gis.ph/v1/api-keys" \
  -H "Authorization: Bearer <SUPABASE_JWT_OR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production key",
    "environment": "live"
  }'

Response

• The response includes a key field one time only. Store it securely.

---

Revoke a Key

POST /v1/api-keys/{id}/revoke

Revoke an API key (sets status = "revoked").

curl -s -X POST "https://api.gis.ph/v1/api-keys/<uuid>/revoke" \
  -H "Authorization: Bearer <SUPABASE_JWT_OR_API_KEY>"

---

Using an API Key

Once you have a key, call any /v1/* data endpoint like this:

curl -s "https://api.gis.ph/v1/datasets" \
  -H "Authorization: Bearer gis_sk_live_<prefix>_<secret>"

Server-side configuration

• Set API_KEY_PEPPER (required) to a long random secret; it is used when hashing API keys server-side.
• API keys are stored hashed (no plaintext stored).