Skip to main content
All API endpoints (except /health and /auth/token) require a JWT bearer token.

​
Obtaining a Token

Request a token from your participant backend: 
curl -X POST https://your-backend.example.com/auth/token

​
Response

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_in": 3600,
    "canton_party_id": "SenderInstitution::209fa2c...b341",
    "role": "institution"
  },
  "meta": {
    "request_id": "req_a1b2c3d4",
    "timestamp": "2025-03-15T09:00:00.000Z"
  }
}

​
Using the Token

Include the token in the Authorization header on all subsequent requests: 
curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  https://your-backend.example.com/api/v1/orders

​
JWT Claims

The token contains these claims:
ClaimDescription
subYour Canton Party ID
canton_party_idYour Canton Party ID (same as sub)
roleYour participant type: institution, custodian, or market-maker
issToken issuer: musubi
audToken audience: musubi-api
expExpiration timestamp (default: 1 hour from issuance)

​
Token Lifecycle

  • Tokens expire after 3600 seconds (1 hour) by default
  • Request a new token before the current one expires
  • Expired tokens return 401 Unauthorized
The /auth/token endpoint is a development convenience. In production, tokens will be issued by an external identity provider (e.g., Keycloak, Auth0) integrated with your organization’s SSO.

​
Verifying Your Identity

Use the /whoami endpoint to confirm your backend’s party identity: 
curl https://your-backend.example.com/whoami

{
  "data": {
    "canton_party_id": "SenderInstitution::209fa2c...b341",
    "role": "institution"
  }
}