Skip to content

Authentication

Send a secret API key as a bearer token:

HTTP
GET /v1/transactions?limit=20 HTTP/1.1
Host: api.example.com
Authorization: Bearer giep_sk_6bf8de7fc0f7_v3vYSslx...
  • A key looks like giep_sk_<12 hex prefix>_<secret>. GIEP stores only its SHA-256 hash; the prefix is a safe handle to show in lists.
  • A key has full access to the merchant (every store and every merchant permission). Use it only from your servers, never in a browser or a mobile app, and keep it in a secrets manager.
  • A revoked key, or a key of a merchant blocked by GIEP staff, answers 401. A merchant paused for non-payment answers 403 merchant_blocked except on billing reads.

Managing keys: in the workspace under Settings > API keys (owners and admins create and revoke, developers list; see the merchant guide), or with these calls made by a signed-in user (session token). A request authenticated with an API key is refused with 403 api_key_management_requires_user: a key can never list, create or revoke keys, so a leaked key cannot mint more. All three are refused in a GIEP support session.

Call What it does
POST /v1/api-keys { "name": "Order system" } Owner/admin. Creates a key. The key field is in this response only.
GET /v1/api-keys Owner/admin/developer. Lists keys: id, name, prefix, createdBy, lastUsedAt, revokedAt. Never the secret.
DELETE /v1/api-keys/{id} Owner/admin. Revokes at once. Idempotent. Audited.

Keys are merchant-wide (every store); there are no separate test and live keys. The first key of a merchant created by GIEP staff is shown once at creation. Rotate by creating a new key, deploying it, checking its last use, then revoking the old one.

Each endpoint in the reference lists the permission it needs (for example payment:create). API keys have them all; signed-in users have the permissions of their role (roles).