Skip to main content

Core API authentication

The Core API's authentication requirements depend on the configured authentication mode. For detailed information about authentication architecture and configuration, see Authentication and authorization.

Authentication by mode​

No authentication mode​

When Core is configured with INSECURE_NONE, all API endpoints are accessible without authentication. No Authorization header is required.

Example request:​

curl -L '/api/organisation/v1' \
  -H 'Accept: application/json'
warning

This mode should only be used in development environments or when authentication is enforced by infrastructure components. See Authentication and authorization for security considerations.

Static token mode​

When Core is configured with STATIC mode, include the configured static token in the Authorization header as a Bearer token.

Example request:​

curl -L '/api/organisation/v1' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer your-static-token'
warning

This mode should only be used in development environments or when authentication is enforced by infrastructure components. See Authentication and authorization for security considerations.

STS mode​

When Core is configured with STS mode, include a valid STS application token in the Authorization header as a Bearer token.

Example request:​

curl -L '/api/organisation/v1' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer eyJhbGciOiJFZERTQSIsImtpZCI6IjIwMjQtMDktZWQyNTUxOS1wcm9kLTAxIn0...'

Token requirements:​

  • Must be a valid JWT signed with keys published at the configured JWKS endpoint
  • Must contain valid aud, iss, and exp claims matching Core's configuration
  • Must include the the organisationId (tenant) for the resources being accessed
  • Must include the permissions array with the necessary permissions for the requested operation

Obtaining STS tokens:​

For information on how to obtain STS tokens, see Obtaining STS tokens.

Authorization failures​

If the token in invalid, expired, or lacks required permissions, the API returns a 401 Unauthorized or 403 Forbidden response.

API surface overview​

The Core API consists of three categories of endpoints with different authentication requirements.

Management endpoints​

/api/*​

Management endpoints provide administrative and operational functionality for credentials, schemas, organizations (tenants), and other platform resources.

Authentication:​

These endpoints respect the configured authentication mode:

  • No authentication mode: All endpoints are accessible without credentials
  • Static token mode: Requires the configured static token in the Authorization header
  • STS mode: Requires a valid STS application token with appropriate permissions

Most operations require specific permissions (for example, CREDENTIAL_ISSUE) which are checked when using STS mode.

STS endpoints​

/ssi/*​

SSI (Self-Sovereign Identity) endpoints implement standard protocols for credential issuance and verification, including OpenID4VC.

Authentication:​

Many SSI endpoints are public and do not require authentication, as they implement protocol-specific security mechanisms. Some endpoints require protocol-specific tokens, for example:

  • /ssi/openid4vci/draft-13/{id}/credential requires an OpenID4VC access token obtained through the credential offer flow
  • /ssi/trust-entity/v1/* endpoints require a remote-agent token for trust registry operations

These protocol-specific tokens are independent of the Core's authentication mode and are passed in request headers as defined by their respective specifications.

System endpoints​

System endpoints provide service health and operational information:

  • /build-info - Build and version details
  • /metrics - System metrics
  • /health - System health check

Authentication:​

When enabled in the configuration, these endpoints are public and accessible regardless of authentication mode.