Create a new API key - Sumvin API

curl --request POST \
  --url https://sis.sumvin.com/v0/organisation/{org_id}/keys \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "production-backend",
  "env_id": "env_01HABCDEFGHIJKL",
  "scopes": [
    "sis.lookup",
    "sis.get_details",
    "sis.get_kyc",
    "sis.token_exchange",
    "sis.get_pints"
  ]
}
'

{
  "id": "<string>",
  "name": "<string>",
  "key": "<string>",
  "meta": {},
  "scopes": [
    "<string>"
  ],
  "_links": {}
}

{
  "detail": "No wallet found with ID 12345 for this user.",
  "error_code": "WAL-404-001",
  "instance": "/v0/wallets/12345",
  "status": 404,
  "title": "Wallet Not Found",
  "trace_id": "abc123-def456-ghi789",
  "type": "https://api.sumvin.com/errors/wal-404-001"
}

{
  "detail": "No wallet found with ID 12345 for this user.",
  "error_code": "WAL-404-001",
  "instance": "/v0/wallets/12345",
  "status": 404,
  "title": "Wallet Not Found",
  "trace_id": "abc123-def456-ghi789",
  "type": "https://api.sumvin.com/errors/wal-404-001"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

{
  "detail": "No wallet found with ID 12345 for this user.",
  "error_code": "WAL-404-001",
  "instance": "/v0/wallets/12345",
  "status": 404,
  "title": "Wallet Not Found",
  "trace_id": "abc123-def456-ghi789",
  "type": "https://api.sumvin.com/errors/wal-404-001"
}

POST

/

v0

/

organisation

/

{org_id}

/

keys

curl --request POST \
  --url https://sis.sumvin.com/v0/organisation/{org_id}/keys \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "production-backend",
  "env_id": "env_01HABCDEFGHIJKL",
  "scopes": [
    "sis.lookup",
    "sis.get_details",
    "sis.get_kyc",
    "sis.token_exchange",
    "sis.get_pints"
  ]
}
'

{
  "id": "<string>",
  "name": "<string>",
  "key": "<string>",
  "meta": {},
  "scopes": [
    "<string>"
  ],
  "_links": {}
}

{
  "detail": "No wallet found with ID 12345 for this user.",
  "error_code": "WAL-404-001",
  "instance": "/v0/wallets/12345",
  "status": 404,
  "title": "Wallet Not Found",
  "trace_id": "abc123-def456-ghi789",
  "type": "https://api.sumvin.com/errors/wal-404-001"
}

{
  "detail": "No wallet found with ID 12345 for this user.",
  "error_code": "WAL-404-001",
  "instance": "/v0/wallets/12345",
  "status": 404,
  "title": "Wallet Not Found",
  "trace_id": "abc123-def456-ghi789",
  "type": "https://api.sumvin.com/errors/wal-404-001"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

{
  "detail": "No wallet found with ID 12345 for this user.",
  "error_code": "WAL-404-001",
  "instance": "/v0/wallets/12345",
  "status": 404,
  "title": "Wallet Not Found",
  "trace_id": "abc123-def456-ghi789",
  "type": "https://api.sumvin.com/errors/wal-404-001"
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

user-agent

string | null

Path Parameters

org_id

string

required

Body

application/json

env_id

string

required

External ID of the environment this key is bound to. Must be one of the caller's accessible environments — passing an env owned by a different organisation returns 404. The env_id is recorded in the key's meta and is used by the public RPC worker's caller-identity check.

Minimum string length: 1

name

string | null

Maximum string length: 255

scopes

string[] | null

Optional scope set the minted key will carry. Omit to provision a key with the full default action set (backwards-compat for partner SDK / curl / Postman clients that don't yet pick scopes). Pass an explicit subset to scope a key to specific operations. Sending an empty list returns SIS-422-007. All values must come from a single partition: rpc.* (public — safe to embed in client-side code) or sis.* (server — for partner backends). Mixing partitions or sending unknown values returns SIS-422-006. See the scope catalogue in the partner docs for the full list of permitted values.

Example:

[
  "sis.lookup",
  "sis.get_details",
  "sis.get_kyc",
  "sis.token_exchange",
  "sis.get_pints"
]

Response

Successful Response

Response for POST /v0/organisation/{org_id}/keys.

Surfaces the minted key, its derived partition (public/server), the explicit scopes set, the persisted Unkey meta (so callers can confirm the env binding), and HAL-style _links. _links.rpc_endpoint and _links.rpc_docs are present ONLY for public-partition keys — server-partition keys see only the navigation/action set.

id

string

required

name

string

required

key

string

required

Plaintext API key, shown only on creation.

meta

Meta · object

required

Persisted Unkey metadata for the key. meta.org_id and meta.env_id carry the caller-identity binding used by the public RPC worker.

Show child attributes

scopes

string[]

required

The scope set the key was minted with (e.g. ["sis.lookup", "sis.get_kyc"] or ["rpc.invoke"]). Mirrors the Unkey permissions list.

partition

enum<string> | null

required

Derived from the key's scope namespace prefix. public for rpc.*-only keys (safe to embed client-side); server for sis.* keys (partner-backend use). Re-mint is the only path between partitions.

Available options:

public,

server

_links

Links · object

HAL-style hypermedia links. Common: self, organisation, environment, revoke, list. Public-partition keys also carry rpc_endpoint (the RPC worker URL to point clients at) and rpc_docs.

Show child attributes

⌘I