stable · api · 0.1.0

Issue a short-lived Realtime grant

POST /api/v1/realtime-grants

Capability Domain: Realtime

Authentication

projectCredential (realtime:connect)

Scope: realtime:connect

Parameters and request body

X-Correlation-ID — header, optional
X-Correlation-ID schema
```
{
    "type": "string",
    "format": "uuid"
}
```

Request schema

application/json

application/json request schema

{
    "type": "object",
    "additionalProperties": false,
    "required": [
        "subject",
        "channels",
        "capabilities"
    ],
    "properties": {
        "subject": {
            "type": "string",
            "maxLength": 180
        },
        "channels": {
            "type": "array",
            "minItems": 1,
            "maxItems": 20,
            "uniqueItems": true,
            "items": {
                "type": "string",
                "maxLength": 180
            }
        },
        "capabilities": {
            "type": "array",
            "minItems": 1,
            "maxItems": 2,
            "uniqueItems": true,
            "items": {
                "type": "string",
                "enum": [
                    "subscribe",
                    "publish"
                ]
            }
        }
    }
}

application/json request example

{
    "subject": "platform-account:30000000-0000-4000-8000-000000000003",
    "channels": [
        "notifications:30000000-0000-4000-8000-000000000003"
    ],
    "capabilities": [
        "subscribe"
    ]
}

Responses and errors

Status	Description
`200`	Short-lived client-scoped realtime grant
`401`	Invalid or revoked Project Credential
`403`	Project Credential lacks realtime grant scope
`422`	Invalid subject, channel, or capability

200 schema

200 response schema

{
    "type": "object",
    "required": [
        "data"
    ],
    "properties": {
        "data": {
            "type": "object",
            "required": [
                "token",
                "expires_at"
            ],
            "properties": {
                "token": {
                    "type": "string"
                },
                "expires_at": {
                    "type": "string",
                    "format": "date-time"
                }
            }
        }
    }
}

401 schema

401 response schema

{
    "type": "object",
    "required": [
        "error"
    ],
    "properties": {
        "error": {
            "type": "object",
            "required": [
                "code",
                "message",
                "retryable",
                "correlation_id",
                "details"
            ],
            "properties": {
                "code": {
                    "type": "string"
                },
                "message": {
                    "type": "string"
                },
                "retryable": {
                    "type": "boolean"
                },
                "correlation_id": {
                    "type": "string",
                    "format": "uuid"
                },
                "details": {
                    "type": "object"
                }
            }
        }
    }
}

403 schema

403 response schema

{
    "type": "object",
    "required": [
        "error"
    ],
    "properties": {
        "error": {
            "type": "object",
            "required": [
                "code",
                "message",
                "retryable",
                "correlation_id",
                "details"
            ],
            "properties": {
                "code": {
                    "type": "string"
                },
                "message": {
                    "type": "string"
                },
                "retryable": {
                    "type": "boolean"
                },
                "correlation_id": {
                    "type": "string",
                    "format": "uuid"
                },
                "details": {
                    "type": "object"
                }
            }
        }
    }
}

422 schema

422 response schema

{
    "type": "object",
    "required": [
        "error"
    ],
    "properties": {
        "error": {
            "type": "object",
            "required": [
                "code",
                "message",
                "retryable",
                "correlation_id",
                "details"
            ],
            "properties": {
                "code": {
                    "type": "string"
                },
                "message": {
                    "type": "string"
                },
                "retryable": {
                    "type": "boolean"
                },
                "correlation_id": {
                    "type": "string",
                    "format": "uuid"
                },
                "details": {
                    "type": "object"
                }
            }
        }
    }
}

200 example

200 response example

{
    "data": {
        "token": "eyJhbGciOiJSUzI1NiIsImtpZCI6InNhbmRib3gifQ.example.signature",
        "expires_at": "2026-08-01T01:05:00Z"
    }
}

422 example

422 response example

{
    "error": {
        "code": "validation_failed",
        "message": "The given data was invalid.",
        "retryable": false,
        "correlation_id": "89000000-0000-4000-8000-000000000001",
        "details": {
            "channels": [
                "At least one channel is required."
            ]
        }
    }
}

Idempotency

Each request issues a new short-lived grant. Request a replacement when reconnecting near or after expiry.