OrbitwriteDocs

API reference

API keys

4 endpoints, served at https://orbitwrite.com/api/v1. Each one lists the credentials it accepts, its parameters and every response it can give.

Endpoints
GET/api/v1/api-keys/permissionsGET/api/v1/api-keysPOST/api/v1/api-keysDEL/api/v1/api-keys/{keyId}

List the permission vocabulary#

GET/api/v1/api-keys/permissions

Every resource, its actions, and what each workspace role grants. Use it to build the scopes object for POST /api-keys.

Authentication

A signed-in session only. The Orbitwrite app calls this; an API key is refused.

Responses

200PermissionCatalog

The permission catalog

Response attributes
resourcesobjectRequired

Every resource and the actions defined on it. A key's scopes must be a subset.

rolesobjectRequired

What each workspace role grants, in the same shape — so a key can be scoped to match a role.

401Error

Not signed in

Response attributes
errorstringRequired
issuesany[]
GET /api/v1/api-keys/permissions
curl -X GET "https://orbitwrite.com/api/v1/api-keys/permissions" \
  -H "Authorization: Bearer $ORBITWRITE_API_KEY"
Response
{
  "resources": {},
  "roles": {}
}

List a workspace's API keys#

GET/api/v1/api-keys

Returns key metadata (never the secret, which is only surfaced once on creation). Any member may read.

Authentication

A signed-in session only. The Orbitwrite app calls this; an API key is refused.

Query parameters

organizationIdstringRequired

At least 1 character.

Responses

200ApiKeyList

The workspace's API keys

Response attributes
keysApiKey[]Required
Child attributes
idstringRequired
namestringRequired
keyPrefixstringRequired

Non-sensitive prefix for the masked UI preview

lastUsedAtstring | nullRequired

ISO 8601.

createdAtstringRequired

ISO 8601.

scopesobject | nullRequired

What the key may do. null means full workspace authority — the implicit grant of every key minted before scopes existed.

400Error

Invalid request

Response attributes
errorstringRequired
issuesany[]
401Error

Not signed in

Response attributes
errorstringRequired
issuesany[]
403Error

Not a member of the organization

Response attributes
errorstringRequired
issuesany[]
GET /api/v1/api-keys
curl -X GET "https://orbitwrite.com/api/v1/api-keys?organizationId=organizationId" \
  -H "Authorization: Bearer $ORBITWRITE_API_KEY"
Response
{
  "keys": [
    {
      "id": "string",
      "name": "string",
      "keyPrefix": "string",
      "lastUsedAt": "string",
      "createdAt": "string",
      "scopes": {}
    }
  ]
}

Create an API key#

POST/api/v1/api-keys

Owner/admin only: a key grants programmatic, org-wide access, so minting one is a privileged action. The response carries the full secret exactly once.

Authentication

A signed-in session only. The Orbitwrite app calls this; an API key is refused.

Body application/json

organizationIdstringRequired

At least 1 character.

namestringRequired

At least 1 character.

scopesobject

What the key may do, as { resource: [action, …] } — e.g. {"post": ["read", "create"], "tag": ["read"]}. Omit to grant the key full workspace authority (the behaviour of every key minted before scopes existed). Prefer the narrowest set the integration needs. Valid resources and actions are listed in GET /api-keys/permissions.

Responses

200CreatedApiKey

The key was created; secret is shown once

Response attributes
okbooleanRequired
secretstringRequired

The full key — surfaced exactly once, never retrievable again

400Error

Invalid request

Response attributes
errorstringRequired
issuesany[]
401Error

Not signed in

Response attributes
errorstringRequired
issuesany[]
403Error

Not a member of the organization

Response attributes
errorstringRequired
issuesany[]
POST /api/v1/api-keys
curl -X POST "https://orbitwrite.com/api/v1/api-keys" \
  -H "Authorization: Bearer $ORBITWRITE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "organizationId": "string",
  "name": "string"
}'
Response
{
  "ok": true,
  "secret": "string"
}

Revoke an API key#

DELETE/api/v1/api-keys/{keyId}

Owner/admin only. The key stops authenticating immediately (its hash row is deleted).

Authentication

A signed-in session only. The Orbitwrite app calls this; an API key is refused.

Path parameters

keyIdstringRequired

At least 1 character.

Query parameters

organizationIdstringRequired

At least 1 character.

Responses

200ApiKeyMutationResult

The key was revoked

Response attributes
okbooleanRequired
400Error

Invalid request

Response attributes
errorstringRequired
issuesany[]
401Error

Not signed in

Response attributes
errorstringRequired
issuesany[]
403Error

Not a member of the organization

Response attributes
errorstringRequired
issuesany[]
404Error

The resource does not exist

Response attributes
errorstringRequired
issuesany[]
DELETE /api/v1/api-keys/{keyId}
curl -X DELETE "https://orbitwrite.com/api/v1/api-keys/{keyId}?organizationId=organizationId" \
  -H "Authorization: Bearer $ORBITWRITE_API_KEY"
Response
{
  "ok": true
}