Skip to content
Turing Space TCS

API Reference

Overview

Section titled “Overview”

This page lists every public and admin endpoint exposed by TCS. Internal endpoints used for inter-service communication are excluded. Health check endpoints (GET /health) are available on all services but omitted from this reference.

For authentication details on each endpoint, see the Authentication reference.

OpenAPI specification

Section titled “OpenAPI specification”

If you need a machine-readable spec for SDK generation or automated tooling, contact the TCS team.

Service Endpoints

Section titled “Service Endpoints”

Base URL: https://auth.turingspace.co

The Authorization Server handles OAuth 2.0 token issuance, DPoP validation, and the authorization code flow. It publishes discovery metadata per RFC 8414.

MethodPathDescriptionAuth
GET/.well-known/oauth-authorization-serverRFC 8414 discovery document. Returns issuer, token_endpoint, pushed_authorization_request_endpoint, and dpop_signing_alg_values_supported among other fields.Public
POST/v1/tokenExchange pre-authorized code or authorization code for access token.Public
POST/v1/parCreate a Pushed Authorization Request session (RFC 9126).Public

The authorization endpoint (GET /v1/authorize), the login form submit (POST /v1/authorize/submit), and the logout endpoint (GET /end_session) are browser-driven and not part of the integration API surface. They are listed in the discovery document for spec compliance.

GET /.well-known/oauth-authorization-server — RFC 8414 AS metadata discovery

Returns the Authorization Server metadata document. Wallets and clients fetch this at startup to discover endpoint URLs, supported grant types, DPoP algorithms, and client attestation requirements.

Auth: Public · Content-Type: N/A (GET)

Response 200

{
  "issuer": "https://auth.turingspace.co",
  "authorization_endpoint": "https://auth.turingspace.co/v1/authorize",
  "token_endpoint": "https://auth.turingspace.co/v1/token",
  "pushed_authorization_request_endpoint": "https://auth.turingspace.co/v1/par",
  "end_session_endpoint": "https://auth.turingspace.co/end_session",
  "response_types_supported": ["code"],
  "grant_types_supported": [
    "authorization_code",
    "urn:ietf:params:oauth:grant-type:pre-authorized_code"
  ],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["attest_jwt_client_auth"],
  "client_attestation_signing_alg_values_supported": ["ES256", "EdDSA"],
  "client_attestation_pop_signing_alg_values_supported": ["ES256", "EdDSA"],
  "dpop_signing_alg_values_supported": ["ES256", "EdDSA"],
  "authorization_details_types_supported": ["openid_credential"],
  "authorization_response_iss_parameter_supported": true,
  "id_token_signing_alg_values_supported": ["ES256"]
}

Errors — None expected under normal operation. Returns 200 always.

See also: Authentication reference

POST /v1/par — Create PAR session (RFC 9126)

Pushes an authorization request to the AS and receives a request_uri handle. The wallet then redirects the user to the AS authorization endpoint with this handle. This is the first step of the authorization-code issuance flow; the pre-authorized_code flow bypasses PAR entirely.

Auth: Public · Content-Type: application/x-www-form-urlencoded

Client attestation required by default. The AS ships with CLIENT_ATTESTATION_REQUIRED_AUTH_CODE=true. Include OAuth-Client-Attestation + OAuth-Client-Attestation-PoP headers or the request will be rejected with 401. See Authentication for details.

Request fields

  • response_type (required, string) — Must be code.
  • client_id (required, string) — Client identifier, e.g. test-wallet.
  • redirect_uri (required, URL) — Auth code delivery URL, e.g. https://wallet.example.com/callback.
  • code_challenge (required, string) — PKCE challenge: base64url(SHA-256(code_verifier)), e.g. E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM.
  • code_challenge_method (required, string) — Must be S256.
  • scope (optional, string) — Credential configuration ID per HAIP §4.3, e.g. TuringCerts_Standard_Credential_v2_sd_jwt.
  • issuer_state (optional, UUID) — Carried from credential offer’s authorization_code.issuer_state.
  • authorization_details (optional, JSON array) — RFC 9396 / OID4VCI §5.1.1, e.g. [{"type":"openid_credential","credential_configuration_id":"UniversityDegree"}].
  • state (optional, string ≤ 4096 chars) — Wallet CSRF token.
  • request_uri — Forbidden in PAR body (RFC 9126 §2.1); rejected with invalid_request.

Response 201

{
  "request_uri": "urn:ietf:params:oauth:request-uri:bwc4JZ-ESnd0kX1aIAr5pg",
  "expires_in": 60
}

Errors — { "error": "...", "error_description": "..." } (RFC 6749 §5.2)

  • 400 invalid_request — Missing required field, request_uri present in body, or issuer_state is not a valid UUID.

See also: Wallet protocol — credential issuance flow

POST /v1/token — Exchange code for access token

Issues an access token in exchange for a pre-authorized code (pre-authorized_code grant) or an authorization code (authorization_code grant). The token response carries a Bearer or DPoP-bound access token used at the Credential Endpoint.

Auth: Public · Content-Type: application/x-www-form-urlencoded

Request fields — pre-authorized_code grant

  • grant_type (required, string) — urn:ietf:params:oauth:grant-type:pre-authorized_code.
  • pre-authorized_code (required, string) — Code from the credential offer, e.g. SplxlOBeZQQYbYS6WxSbIA.
  • tx_code (conditional, string) — Transaction code (user PIN) if tx_code is present in the offer, e.g. 123456.

Request fields — authorization_code grant

  • grant_type (required, string) — authorization_code.
  • code (required, string) — Authorization code from the redirect callback.
  • code_verifier (required, string) — PKCE verifier, e.g. dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk.
  • redirect_uri (required, string) — Must match the URI in the PAR session.
  • client_id (required, string) — Client identifier.

Response 200

{
  "access_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "DPoP",
  "expires_in": 3600
}

token_type is DPoP when the request included a DPoP header, otherwise Bearer.

Errors — { "error": "...", "error_description": "..." } (RFC 6749 §5.2)

  • 400 invalid_grant — Expired or already-used pre-authorized code.
  • 400 unsupported_grant_type — Unknown grant_type value.
  • 400 use_dpop_nonce — AS requires a fresh DPoP nonce; retry with DPoP-Nonce header.
  • 400 invalid_dpop_proof — Malformed or expired DPoP proof JWT.

See also: Wallet protocol — token exchange

What’s Next

Section titled “What’s Next”