Calimero Node Server API (1.0.0)

Download OpenAPI specification:Download

URL: https://github.com/calimero-network/core

API documentation for the Calimero Node Server. The server provides endpoints for:

Admin API: Node administration, application management, context management
Auth API: Authentication and key management (available when embedded auth mode is enabled)
JSON-RPC: Execute queries and mutations on contexts
WebSocket: Real-time event subscriptions
SSE: Server-Sent Events for real-time event streaming

Authentication Modes:

Proxy mode (default): Uses auth headers generated with createAuthHeader from the calimero sdk library. Auth endpoints are provided by an external mero-auth service.
Embedded auth mode: Uses JWT tokens in the Authorization header (e.g., Authorization: Bearer <token>). Auth endpoints are available at /auth and /admin paths.

Admin API - Public

Public admin endpoints (no authentication required)

Health Check

Checks the health of the API

Responses

Response samples

200

Content type

application/json

{"data": {"status": "alive"
}
}

Authentication Status

Checks if the current request is authenticated

Responses

Response samples

200

Content type

application/json

{"data": {"status": "alive"
}
}

Get Certificate

Retrieves the node's certificate

Responses

Admin API - Protected

Protected admin endpoints (authentication required)

Install Application

Installs a new application in the node

Authorizations:

BearerAuthAuthHeader

Request Body schema: application/json

url required	string <uri> URL to download the application
hash	string Expected hash of the application (optional)
metadata required	Array of integers[ items [ 0 .. 255 ] ] Application metadata as byte array (each element is a byte 0-255)
package	string Package name (optional)
version	string Version (optional)

Responses

Request samples

Payload

Content type

application/json

{"url": "http://example.com",
"hash": "string",
"metadata": [255
],
"package": "string",
"version": "string"
}

Response samples

200
401
500

Content type

application/json

{"data": {"applicationId": "string"
}
}

Install Dev Application

Installs a development application from local path

Authorizations:

BearerAuthAuthHeader

Request Body schema: application/json

path required	string Local file system path to the application
metadata required	Array of integers[ items [ 0 .. 255 ] ] Application metadata as byte array (each element is a byte 0-255)
package	string Package name (optional)
version	string Version (optional)

Responses

Request samples

Payload

Content type

application/json

{"path": "string",
"metadata": [255
],
"package": "string",
"version": "string"
}

Response samples

200
401
500

Content type

application/json

{"data": {"applicationId": "string"
}
}

List Applications

Lists all installed applications in the node

Authorizations:

BearerAuthAuthHeader

Responses

Response samples

200
401
500

Content type

application/json

{"data": {"apps": [{"applicationId": "string",
"metadata": [255
]
}
]
}
}

Get Application

Retrieves details of a specific application

Authorizations:

BearerAuthAuthHeader

path Parameters

application_id

required

string

Responses

Response samples

200
401
500

Content type

application/json

{"data": {"application": {"applicationId": "string",
"metadata": [255
]
}
}
}

Uninstall Application

Uninstalls an application from the node

Authorizations:

BearerAuthAuthHeader

path Parameters

application_id

required

string

Responses

Response samples

200
401
500

Content type

application/json

{"data": {"applicationId": "string"
}
}

List Packages

Lists all available packages

Authorizations:

BearerAuthAuthHeader

Responses

Response samples

200
401
500

Content type

application/json

{"packages": ["string"
]
}

List Versions

Lists all versions for a specific package

Authorizations:

BearerAuthAuthHeader

path Parameters

package

required

string

Responses

Response samples

200
401
500

Content type

application/json

{"versions": ["string"
]
}

Get Latest Version

Gets the latest version of a package

Authorizations:

BearerAuthAuthHeader

path Parameters

package

required

string

Responses

Response samples

200
401
500

Content type

application/json

{"applicationId": "string"
}

List Contexts

Lists all contexts

Authorizations:

BearerAuthAuthHeader

Responses

Response samples

200
401
500

Content type

application/json

{"data": {"contexts": [{"contextId": "string",
"applicationId": "string",
"protocol": "string"
}
]
}
}

Create Context

Creates a new context

Authorizations:

BearerAuthAuthHeader

Request Body schema: application/json

protocol required	string
applicationId required	string
contextSeed	string Optional context seed hash
initializationParams required	Array of integers[ items [ 0 .. 255 ] ] Initialization parameters as byte array (each element is a byte 0-255)

Responses

Request samples

Payload

Content type

application/json

{"protocol": "string",
"applicationId": "string",
"contextSeed": "string",
"initializationParams": [255
]
}

Response samples

200
401
500

Content type

application/json

{"data": {"contextId": "string",
"memberPublicKey": "string"
}
}

Get Context

Retrieves details of a specific context

Authorizations:

BearerAuthAuthHeader

path Parameters

context_id

required

string

Responses

Response samples

200
401
500

Content type

application/json

{"data": {"contextId": "string",
"applicationId": "string",
"protocol": "string"
}
}

Delete Context

Deletes a specific context

Authorizations:

BearerAuthAuthHeader

path Parameters

context_id

required

string

Responses

Response samples

200
401
500

Content type

application/json

{"data": {"isDeleted": true
}
}

Get Context Storage

Retrieves storage information for a specific context

Authorizations:

BearerAuthAuthHeader

path Parameters

context_id

required

string

Responses

Response samples

200
401
500

Content type

application/json

{"data": {"sizeInBytes": 0
}
}

Get Context Identities

Lists identities associated with a specific context

Authorizations:

BearerAuthAuthHeader

path Parameters

context_id

required

string

Responses

Response samples

200
401
500

Content type

application/json

{"data": {"identities": ["string"
]
}
}

Get Owned Context Identities

Lists identities owned by the node for a specific context

Authorizations:

BearerAuthAuthHeader

path Parameters

context_id

required

string

Responses

Response samples

200
401
500

Content type

application/json

{"data": {"identities": ["string"
]
}
}

Invite to Context

Invites a user to join a context

Authorizations:

BearerAuthAuthHeader

Request Body schema: application/json

contextId required	string
inviterId required	string
inviteeId required	string

Responses

Request samples

Payload

Content type

application/json

{"contextId": "string",
"inviterId": "string",
"inviteeId": "string"
}

Response samples

200
401
500

Content type

application/json

{"data": { }
}

Create Open Invitation

Creates an open invitation for a context

Authorizations:

BearerAuthAuthHeader

Request Body schema: application/json

contextId required	string
inviterId required	string
validForBlocks required	integer <int64>

Responses

Request samples

Payload

Content type

application/json

{"contextId": "string",
"inviterId": "string",
"validForBlocks": 0
}

Response samples

200
401
500

Content type

application/json

{"data": { }
}

Invite Specialized Node

Invites a specialized node (e.g., read-only TEE node) to join a context

Authorizations:

BearerAuthAuthHeader

Request Body schema: application/json

contextId required	string
inviterId	string or null Optional inviter identity - defaults to context's default identity if not provided

Responses

Request samples

Payload

Content type

application/json

{"contextId": "string",
"inviterId": "string"
}

Response samples

200
401
500

Content type

application/json

{"data": {"nonce": "string"
}
}

Join Context

Joins a context using an invitation payload

Authorizations:

BearerAuthAuthHeader

Request Body schema: application/json

invitationPayload

required

object

Context invitation payload

Responses

Request samples

Payload

Content type

application/json

{"invitationPayload": { }
}

Response samples

200
401
500

Content type

application/json

{"data": {"contextId": "string",
"memberPublicKey": "string"
}
}

Join Context by Open Invitation

Joins a context using an open invitation

Authorizations:

BearerAuthAuthHeader

Request Body schema: application/json

invitation required	object Signed open invitation
newMemberPublicKey required	string

Responses

Request samples

Payload

Content type

application/json

{"invitation": { },
"newMemberPublicKey": "string"
}

Response samples

200
401
500

Content type

application/json

{"data": {"contextId": "string",
"memberPublicKey": "string"
}
}

Update Context Application

Updates the application for a context

Authorizations:

BearerAuthAuthHeader

path Parameters

context_id

required

string

Request Body schema: application/json

applicationId required	string
executorPublicKey required	string

Responses

Request samples

Payload

Content type

application/json

{"applicationId": "string",
"executorPublicKey": "string"
}

Response samples

200
401
500

Content type

application/json

{"data": { }
}

Get Contexts for Application

Lists all contexts for a specific application

Authorizations:

BearerAuthAuthHeader

path Parameters

application_id

required

string

Responses

Response samples

200
401
500

Content type

application/json

{"data": {"contexts": [{"contextId": "string",
"applicationId": "string",
"protocol": "string"
}
]
}
}

Get Contexts with Executors for Application

Lists all contexts with executors for a specific application

Authorizations:

BearerAuthAuthHeader

path Parameters

application_id

required

string

Responses

Response samples

200
401
500

Content type

application/json

{"data": {"contexts": [{"contextId": "string",
"applicationId": "string",
"protocol": "string"
}
]
}
}

Grant Capabilities

Grants capabilities to a user in a context

Authorizations:

BearerAuthAuthHeader

path Parameters

context_id

required

string

Request Body schema: application/json

contextId required	string
granterId required	string
granteeId required	string
capability required	string Capability type

Responses

Request samples

Payload

Content type

application/json

{"contextId": "string",
"granterId": "string",
"granteeId": "string",
"capability": "string"
}

Response samples

200
401
500

Content type

application/json

{"data": { }
}

Revoke Capabilities

Revokes capabilities from a user in a context

Authorizations:

BearerAuthAuthHeader

path Parameters

context_id

required

string

Request Body schema: application/json

contextId required	string
revokerId required	string
revokeeId required	string
capability required	string Capability type

Responses

Request samples

Payload

Content type

application/json

{"contextId": "string",
"revokerId": "string",
"revokeeId": "string",
"capability": "string"
}

Response samples

200
401
500

Content type

application/json

{"data": { }
}

Get Proposals

Retrieves proposals for a context with pagination

Authorizations:

BearerAuthAuthHeader

path Parameters

context_id

required

string

Request Body schema: application/json

offset required	integer <int32>
limit required	integer <int32>

Responses

Request samples

Payload

Content type

application/json

{"offset": 0,
"limit": 0
}

Response samples

200
401
500

Content type

application/json

{"data": [{ }
]
}

Get Proposal

Retrieves a specific proposal

Authorizations:

BearerAuthAuthHeader

path Parameters

context_id required	string
proposal_id required	string

Responses

Response samples

200
401
500

Content type

application/json

{"data": { }
}

Create and Approve Proposal

Creates a proposal and immediately approves it

Authorizations:

BearerAuthAuthHeader

path Parameters

context_id

required

string

Request Body schema: application/json

signerId required	string
proposal required	object (Proposal) Proposal structure (details depend on implementation)

Responses

Request samples

Payload

Content type

application/json

{"signerId": "string",
"proposal": { }
}

Response samples

200
401
500

Content type

application/json

{"data": { }
}

Approve Proposal

Approves an existing proposal

Authorizations:

BearerAuthAuthHeader

path Parameters

context_id

required

string

Request Body schema: application/json

signerId required	string
proposalId required	string

Responses

Request samples

Payload

Content type

application/json

{"signerId": "string",
"proposalId": "string"
}

Response samples

200
401
500

Content type

application/json

{"data": { }
}

Get Number of Active Proposals

Gets the count of active proposals for a context

Authorizations:

BearerAuthAuthHeader

path Parameters

context_id

required

string

Responses

Response samples

200
401
500

Content type

application/json

{"data": 0
}

Get Number of Proposal Approvals

Gets the number of approvals for a specific proposal

Authorizations:

BearerAuthAuthHeader

path Parameters

context_id required	string
proposal_id required	string

Responses

Response samples

200
401
500

Content type

application/json

{"data": { }
}

Get Proposal Approvers

Gets the list of users who approved a proposal

Authorizations:

BearerAuthAuthHeader

path Parameters

context_id required	string
proposal_id required	string

Responses

Response samples

200
401
500

Content type

application/json

{"data": [{ }
]
}

Get Context Value

Retrieves a value from context storage by key

Authorizations:

BearerAuthAuthHeader

path Parameters

context_id

required

string

Request Body schema: application/json

key

required

string

Responses

Request samples

Payload

Content type

application/json

{"key": "string"
}

Response samples

200
401
500

Content type

application/json

{"data": [255
]
}

Get Context Storage Entries

Retrieves context storage entries with pagination

Authorizations:

BearerAuthAuthHeader

path Parameters

context_id

required

string

Request Body schema: application/json

offset required	integer <int32>
limit required	integer <int32>

Responses

Request samples

Payload

Content type

application/json

{"offset": 0,
"limit": 0
}

Response samples

200
401
500

Content type

application/json

{"data": [{ }
]
}

Get Proxy Contract

Retrieves the proxy contract address for a context

Authorizations:

BearerAuthAuthHeader

path Parameters

context_id

required

string

Responses

Response samples

200
401
500

Content type

application/json

{"data": "string"
}

Sync Contexts

Synchronizes all contexts or a specific context

Authorizations:

BearerAuthAuthHeader

Responses

Response samples

200
401
500

Content type

application/json

{"data": { }
}

Sync Context

Synchronizes a specific context

Authorizations:

BearerAuthAuthHeader

path Parameters

context_id

required

string

Responses

Response samples

200
401
500

Content type

application/json

{"data": { }
}

Generate Context Identity

Generates a new identity for a context

Authorizations:

BearerAuthAuthHeader

Responses

Response samples

200
401
500

Content type

application/json

{"data": {"publicKey": "string"
}
}

Get Peers Count

Gets the number of connected peers

Authorizations:

BearerAuthAuthHeader

Responses

Response samples

200
401
500

Content type

application/json

{"count": 0
}

List Blobs

Lists all blobs

Authorizations:

BearerAuthAuthHeader

Responses

Response samples

200
401
500

Content type

application/json

{"data": {"blobs": [{"blob_id": "string",
"size": 0,
"hash": "string"
}
]
}
}

Upload Blob

Uploads a blob (binary data)

Authorizations:

BearerAuthAuthHeader

query Parameters

hash	string Expected hash of the blob for verification
context_id	string Context ID to announce the blob to for network discovery

Request Body schema: application/octet-stream

string <binary>

Responses

Response samples

200
401
500

Content type

application/json

{"data": {"blob_id": "string",
"size": 0,
"hash": "string"
}
}

Download Blob

Downloads a blob by ID

Authorizations:

BearerAuthAuthHeader

path Parameters

blob_id

required

string

Responses

Response samples

401
500

Content type

application/json

{"error": "string"
}

Get Blob Info

Gets metadata information about a blob

Authorizations:

BearerAuthAuthHeader

path Parameters

blob_id

required

string

Responses

Response samples

401
500

Content type

application/json

{"error": "string"
}

Delete Blob

Deletes a blob by ID

Authorizations:

BearerAuthAuthHeader

path Parameters

blob_id

required

string

Responses

Response samples

200
401
500

Content type

application/json

{"blob_id": "string",
"deleted": true
}

Create Context Alias

Creates an alias for a context ID

Authorizations:

BearerAuthAuthHeader

Request Body schema: application/json

alias required	string
contextId required	string

Responses

Request samples

Payload

Content type

application/json

{"alias": "string",
"contextId": "string"
}

Response samples

200
401
500

Content type

application/json

{"data": { }
}

Create Application Alias

Creates an alias for an application ID

Authorizations:

BearerAuthAuthHeader

Request Body schema: application/json

alias required	string
applicationId required	string

Responses

Request samples

Payload

Content type

application/json

{"alias": "string",
"applicationId": "string"
}

Response samples

200
401
500

Content type

application/json

{"data": { }
}

Create Identity Alias

Creates an alias for an identity within a context

Authorizations:

BearerAuthAuthHeader

path Parameters

context

required

string

Request Body schema: application/json

alias required	string
identity required	string

Responses

Request samples

Payload

Content type

application/json

{"alias": "string",
"identity": "string"
}

Response samples

200
401
500

Content type

application/json

{"data": { }
}

Lookup Context Alias

Looks up a context ID by alias name

Authorizations:

BearerAuthAuthHeader

path Parameters

name

required

string

Responses

Response samples

200
401
500

Content type

application/json

{"data": {"value": "string"
}
}

Lookup Application Alias

Looks up an application ID by alias name

Authorizations:

BearerAuthAuthHeader

path Parameters

name

required

string

Responses

Response samples

200
401
500

Content type

application/json

{"data": {"value": "string"
}
}

Lookup Identity Alias

Looks up an identity by alias name within a context

Authorizations:

BearerAuthAuthHeader

path Parameters

context required	string
name required	string

Responses

Response samples

200
401
500

Content type

application/json

{"data": {"value": "string"
}
}

List Context Aliases

Lists all context aliases

Authorizations:

BearerAuthAuthHeader

Responses

Response samples

200
401
500

Content type

application/json

{"data": {"property1": "string",
"property2": "string"
}
}

List Application Aliases

Lists all application aliases

Authorizations:

BearerAuthAuthHeader

Responses

Response samples

200
401
500

Content type

application/json

{"data": {"property1": "string",
"property2": "string"
}
}

List Identity Aliases

Lists all identity aliases for a context

Authorizations:

BearerAuthAuthHeader

path Parameters

context

required

string

Responses

Response samples

200
401
500

Content type

application/json

{"data": {"property1": "string",
"property2": "string"
}
}

Delete Context Alias

Deletes a context alias

Authorizations:

BearerAuthAuthHeader

path Parameters

name

required

string

Responses

Response samples

200
401
500

Content type

application/json

{"data": { }
}

Delete Application Alias

Deletes an application alias

Authorizations:

BearerAuthAuthHeader

path Parameters

name

required

string

Responses

Response samples

200
401
500

Content type

application/json

{"data": { }
}

Delete Identity Alias

Deletes an identity alias within a context

Authorizations:

BearerAuthAuthHeader

path Parameters

context required	string
name required	string

Responses

Response samples

200
401
500

Content type

application/json

{"data": { }
}

JSON-RPC

JSON-RPC endpoint for executing queries and mutations

JSON-RPC Request

Handles JSON-RPC requests. Supports the execute method for querying and mutating context state.

Note: When embedded auth mode is enabled, all JSON-RPC requests require authentication via JWT tokens in the Authorization header.

Authorizations:

BearerAuthAuthHeader

Request Body schema: application/json

jsonrpc required	string Value: "2.0"
required	(string or null) or (integer or null)
method	string Value: "execute"
	object (ExecutionRequest)

Responses

Request samples

Payload

Content type

application/json

{"jsonrpc": "2.0",
"id": "string",
"method": "execute",
"params": {"contextId": "string",
"method": "string",
"argsJson": { },
"executorPublicKey": "string",
"substitute": [ ]
}
}

Response samples

200
401
500

Content type

application/json

{"jsonrpc": "2.0",
"id": "string",
"result": {"output": { }
},
"error": {"type": "string",
"data": "string"
}
}

WebSocket

WebSocket endpoint for real-time event subscriptions

WebSocket Connection

Establishes a WebSocket connection for real-time event subscriptions.

Note: When embedded auth mode is enabled, WebSocket connections require authentication via JWT tokens in the Authorization header during the initial handshake.

Important: WebSocket connections are unidirectional for events - the server pushes events to subscribed clients. For executing transactions (mutate) or reading state (query), clients must use the separate JSON-RPC endpoint.

Message Format:

Subscribe: {"id": 1, "method": "subscribe", "params": {"contextIds": ["context_1"]}}
Unsubscribe: {"id": 2, "method": "unsubscribe", "params": {"contextIds": ["context_1"]}}

Authorizations:

BearerAuthAuthHeader

header Parameters

upgrade

required

string

Default: websocket

Responses

Response samples

401

Content type

application/json

{"error": "string"
}

SSE

Server-Sent Events endpoint for real-time event streaming

Establish SSE Connection

Opens a long-lived HTTP connection for receiving server-sent events.

Note: When embedded auth mode is enabled, SSE connections require authentication via JWT tokens in the Authorization header when opening the connection.

The very first message received is a connect event containing a session_id. This session_id must be used for subsequent subscription requests.

Reconnection: Clients can reconnect using the Last-Event-ID header with format {session_id}-{event_number}.

Authorizations:

BearerAuthAuthHeader

header Parameters

Last-Event-ID

string

Session ID and event number for reconnection (format: {session_id}-{event_number})

Responses

Response samples

401

Content type

application/json

{"error": "string"
}

Subscribe/Unsubscribe to Contexts

Subscribes or unsubscribes the active SSE connection to one or more contexts.

Request Format:

Subscribe: {"id": "session_id", "method": "subscribe", "params": {"contextIds": ["context_1"]}}
Unsubscribe: {"id": "session_id", "method": "unsubscribe", "params": {"contextIds": ["context_1"]}}

The id field must be the session_id received from the initial connect event.

Authorizations:

BearerAuthAuthHeader

Request Body schema: application/json

id required	string Session ID received from the initial connect event
method required	string Enum: "subscribe" "unsubscribe"
required	object (SseContextIds)

Responses

Request samples

Payload

Content type

application/json

{"id": "string",
"method": "subscribe",
"params": {"contextIds": ["string"
]
}
}

Response samples

200
401
500

Content type

application/json

{"body": {"result": {"status": "subscribed",
"contexts": ["string"
],
"requested": ["string"
]
},
"error": { }
}
}

Get SSE Session

Gets information about an SSE session

Authorizations:

BearerAuthAuthHeader

path Parameters

session_id

required

string

Responses

Response samples

200
401
500

Content type

application/json

{"body": {"result": {"sessionId": "string",
"subscriptions": ["string"
],
"eventCounter": 0,
"status": "active"
},
"error": { }
}
}

TEE

Trusted Execution Environment attestation endpoints

Get TEE Info

Gets information about the Trusted Execution Environment

Responses

Response samples

200
500

Content type

application/json

{"data": {"cloudProvider": "gcp",
"osImage": "ubuntu-2404-tdx-v20250115",
"mrtd": "string"
}
}

TEE Attestation

Generates a TEE attestation quote

Request Body schema: application/json

nonce required	string Client-provided nonce for freshness (32 bytes as hex string)
applicationId	string or null Optional application ID to include in attestation

Responses

Request samples

Payload

Content type

application/json

{"nonce": "string",
"applicationId": "string"
}

Response samples

200
500

Content type

application/json

{"data": {"quoteB64": "string",
"quote": {"header": {"version": 0,
"attestationKeyType": 0,
"teeType": 0,
"qeVendorId": "string",
"userData": "string"
},
"body": {"tdxVersion": "string",
"teeTcbSvn": "string",
"mrseam": "string",
"mrsignerseam": "string",
"seamattributes": "string",
"tdattributes": "string",
"xfam": "string",
"mrtd": "string",
"mrconfigid": "string",
"mrowner": "string",
"mrownerconfig": "string",
"rtmr0": "string",
"rtmr1": "string",
"rtmr2": "string",
"rtmr3": "string",
"reportdata": "string",
"teeTcbSvn2": "string",
"mrservicetd": "string"
},
"signature": "string",
"attestationKey": "string",
"certificationData": "string"
}
}
}

Verify TEE Quote

Verifies a TEE attestation quote

Request Body schema: application/json

quoteB64 required	string Base64-encoded TDX quote to verify
nonce required	string Client-provided nonce that should match report_data[0..32] (64 hex chars = 32 bytes)
expectedApplicationHash	string or null Optional expected application hash that should match report_data[32..64] (64 hex chars = 32 bytes)

Responses

Request samples

Payload

Content type

application/json

{"quoteB64": "string",
"nonce": "string",
"expectedApplicationHash": "string"
}

Response samples

200
500

Content type

application/json

{"data": {"quoteVerified": true,
"nonceVerified": true,
"applicationHashVerified": true,
"quote": {"header": {"version": 0,
"attestationKeyType": 0,
"teeType": 0,
"qeVendorId": "string",
"userData": "string"
},
"body": {"tdxVersion": "string",
"teeTcbSvn": "string",
"mrseam": "string",
"mrsignerseam": "string",
"seamattributes": "string",
"tdattributes": "string",
"xfam": "string",
"mrtd": "string",
"mrconfigid": "string",
"mrowner": "string",
"mrownerconfig": "string",
"rtmr0": "string",
"rtmr1": "string",
"rtmr2": "string",
"rtmr3": "string",
"reportdata": "string",
"teeTcbSvn2": "string",
"mrservicetd": "string"
},
"signature": "string",
"attestationKey": "string",
"certificationData": "string"
}
}
}

Auth API - Public

Public authentication endpoints (no authentication required). Available when embedded auth mode is enabled.

Auth Login UI

Serves the React SPA for authentication. This is the main entry point for the authentication UI.

Responses

Get Signing Challenge

Gets a signing challenge for wallet-based authentication. The client signs this challenge and sends it back via the /auth/token endpoint.

Responses

Response samples

200
500

Content type

application/json

{"data": {"challenge": "string",
"nonce": "string"
}
}

Exchange Challenge for Token

Exchanges a signed challenge for a root key JWT token. The client must sign the challenge received from /auth/challenge and include the signature in the request.

Request Body schema: application/json

auth_method required	string Enum: "near_wallet" "user_password" "eth_wallet" "starknet_wallet" "icp_wallet" Authentication method to use
public_key required	string Public key of the authenticating user
client_name required	string Name of the client application
timestamp required	integer <int64> Timestamp of the request
provider_data required	object Provider-specific authentication data (signature, wallet address, etc.)
permissions	Array of strings Requested permissions (optional)

Responses

Request samples

Payload

Content type

application/json

{"auth_method": "near_wallet",
"public_key": "string",
"client_name": "string",
"timestamp": 0,
"provider_data": { },
"permissions": ["string"
]
}

Response samples

200
500

Content type

application/json

{"data": {"access_token": "string",
"refresh_token": "string",
"expires_in": 0
}
}

Refresh Token

Refreshes an expired access token using a refresh token.

Request Body schema: application/json

access_token required	string The expired access token
refresh_token required	string Refresh token to exchange for new access token

Responses

Request samples

Payload

Content type

application/json

{"access_token": "string",
"refresh_token": "string"
}

Response samples

200
500

Content type

application/json

{"data": {"access_token": "string",
"refresh_token": "string",
"expires_in": 0
}
}

List Auth Providers

Lists all available authentication providers (e.g., NEAR wallet, username/password).

Responses

Response samples

200
500

Content type

application/json

{"providers": [{"id": "string",
"name": "string",
"enabled": true
}
],
"count": 0
}

Get Service Identity

Gets service information and identity details.

Responses

Response samples

200
500

Content type

application/json

{"data": {"service": "string",
"version": "string",
"identity": "string"
}
}

Validate Token (GET)

Validates a JWT token. Designed for auth proxy use. Returns empty string on success (200 OK). Auth info in headers: X-Auth-User, X-Auth-Permissions. If response is not 401, the token is valid.

header Parameters

Authorization

required

string

Bearer token to validate

Responses

Response samples

500

Content type

application/json

{"error": "string"
}

Validate Token (POST)

Validates a JWT token. Designed for auth proxy use. Returns empty string on success (200 OK). Auth info in headers: X-Auth-User, X-Auth-Permissions. If response is not 401, the token is valid.

Request Body schema: application/json

token

required

string

JWT token to validate

Responses

Request samples

Payload

Content type

application/json

{"token": "string"
}

Response samples

500

Content type

application/json

{"error": "string"
}

Auth Service Health Check

Checks the health of the authentication service.

Responses

Response samples

200

Content type

application/json

{"data": {"status": "alive"
}
}

Auth Callback

OAuth callback endpoint for authentication flows.

query Parameters

callback-url

string

Callback URL to redirect to after authentication

Responses

Auth API - Protected

Protected authentication endpoints (require JWT token). Available when embedded auth mode is enabled.

Revoke Token

Revokes the current JWT token, invalidating it immediately.

Authorizations:

BearerAuth

Responses

Response samples

200
401
500

Content type

application/json

{"data": {"revoked": true
}
}

List Root Keys

Lists all root keys associated with the authenticated user.

Authorizations:

BearerAuth

Responses

Response samples

200
401
500

Content type

application/json

{"data": [{"key_id": "string",
"public_key": "string",
"client_name": "string",
"created_at": "2019-08-24T14:15:22Z",
"permissions": ["string"
]
}
]
}

Create Root Key

Creates a new root key.

Authorizations:

BearerAuth

Request Body schema: application/json

public_key required	string Public key for the root key
client_name required	string Name of the client
permissions	Array of strings Permissions for the root key

Responses

Request samples

Payload

Content type

application/json

{"public_key": "string",
"client_name": "string",
"permissions": ["string"
]
}

Response samples

200
401
500

Content type

application/json

{"data": {"key_id": "string",
"public_key": "string",
"client_name": "string",
"created_at": "2019-08-24T14:15:22Z",
"permissions": ["string"
]
}
}

Delete Root Key

Deletes a root key by ID.

Authorizations:

BearerAuth

path Parameters

key_id

required

string

Responses

Response samples

200
401
500

Content type

application/json

{"data": {"deleted": true
}
}

List Client Keys

Lists all client keys.

Authorizations:

BearerAuth

Responses

Response samples

200
401
500

Content type

application/json

{"data": [{"key_id": "string",
"root_key_id": "string",
"context_id": "string",
"context_identity": "string",
"permissions": ["string"
],
"created_at": "2019-08-24T14:15:22Z"
}
]
}

Generate Client Key

Generates a new client key with specified permissions and context associations.

Authorizations:

BearerAuth

Request Body schema: application/json

context_id required	string Context ID to associate with the client key
context_identity required	string Context identity for the client key
permissions required	Array of strings Permissions for the client key

Responses

Request samples

Payload

Content type

application/json

{"context_id": "string",
"context_identity": "string",
"permissions": ["string"
]
}

Response samples

200
401
500

Content type

application/json

{"data": {"key_id": "string",
"root_key_id": "string",
"context_id": "string",
"context_identity": "string",
"permissions": ["string"
],
"created_at": "2019-08-24T14:15:22Z"
}
}

Delete Client Key

Deletes a client key associated with a root key.

Authorizations:

BearerAuth

path Parameters

key_id required	string
client_id required	string

Responses

Response samples

200
401
500

Content type

application/json

{"data": {"deleted": true
}
}

Get Key Permissions

Gets the permissions for a specific key.

Authorizations:

BearerAuth

path Parameters

key_id

required

string

Responses

Response samples

200
401
500

Content type

application/json

{"data": ["string"
]
}

Update Key Permissions

Updates the permissions for a specific key.

Authorizations:

BearerAuth

path Parameters

key_id

required

string

Request Body schema: application/json

permissions

required

Array of strings

New permissions to set

Responses

Request samples

Payload

Content type

application/json

{"permissions": ["string"
]
}

Response samples

200
401
500

Content type

application/json

{"data": ["string"
]
}

Get Protected Identity

Gets protected identity information (requires authentication).

Authorizations:

BearerAuth

Responses

Response samples

200
401
500

Content type

application/json

{"data": {"service": "string",
"version": "string",
"identity": "string"
}
}

Get Auth Service Metrics

Gets metrics for the authentication service.

Authorizations:

BearerAuth

Responses

Response samples

200
401
500

Content type

application/json

{"data": {"property1": { },
"property2": { }
}
}