Runtime API
The platform API at https://api.ghayma.tech, as a project API key (gsk_…)
reaches it. A key belongs to one project and opens a deny-by-default allowlist of
that project’s application routes — the surface your server code and pipelines
use — on the resources it was granted. For how keys are created, granted, rolled
and injected, see Project API Keys.
Grants
The 36 operations group into four kinds of resource. A key you create reaches a
route only through a grant on the resource the route acts on, at the route’s
level or above; a site’s managed GHAYMA_API_KEY only through that site’s
connections.
| Kind | Levels | Reaches | Operations |
|---|---|---|---|
auth_app | read, admin | Administer the project’s auth apps and their end users | 11 |
bucket | read, read-write | Buckets, objects, and presigned upload and download URLs | 12 |
database | read | Read databases, their metrics and — with a site’s key — their credentials | 4 |
site | deploy | Upload deploys; read deployments, logs, sites and the project | 9 |
The key guide lists what each level allows.
Credentials
Send the key as a Bearer credential:
curl https://api.ghayma.tech/api/v1/auth-apps \
-H "Authorization: Bearer gsk_..."Deny rules
The surface is an allowlist, and each refusal is shaped so a key never reveals what it cannot touch:
| Response | When |
|---|---|
401 | The key is missing or invalid |
403 | The route is outside the allowlist, or it spans a kind the key holds no grant of — a list, or the project itself (insufficient token scope) |
403 with a code | The resource is in the key’s project, but the key may not act on it — see Refusals |
404 | The resource lives in another project — so a key cannot probe what else its owner owns |
Refusals
A key refused a resource of its own project gets a 403 whose code names the
reason, so your code can branch on it:
{ "error": "this key has no access to that bucket", "code": "not_granted" }| Code | Key | error | Fix |
|---|---|---|---|
not_granted | One you created — or a site’s key on a route across every site | this key has no access to that bucket — or database, auth app, site | Edit the key’s access to grant that resource |
read_only_grant | One you created | this key can only read that bucket — or auth app | Raise that grant to read-write, or to admin for an auth app |
not_connected | A site’s GHAYMA_API_KEY | this site is not connected to that bucket — or database, auth app | Connect the site to it — an auth app at admin |
read_only_connection | A site’s GHAYMA_API_KEY | this site's connection to that bucket is read-only | Change the connection’s level to read-write |
In @ghayma/sdk the code is err.code on the thrown GhaymaError.
Reading a database’s or a bucket’s credentials returns the key’s site’s own
connection credential, so it needs a site’s managed
key: a key tied to no site answers 403 with
code site_key_required, a service the site isn’t connected to answers
403 with code not_connected, and a connection that has no credential of its
own yet answers 409 with code no_own_credential — the platform gives it one
as soon as the service can (it retries every ten minutes).
This is the server / project-key surface. Your auth apps’ end users
sign in against the separate auth service at https://auth.ghayma.tech,
documented at Auth Service API — a gsk_ key does not go
there.
Contract
The reference below is rendered from the live OpenAPI 3.0.3 document the API publishes. Download it as openapi.yaml or openapi.json to generate a client in any language or to import it into Postman or Insomnia.