Authentication

Overview

TCS uses three authentication methods depending on the endpoint you are calling:

• API Key — A static key sent in the X-API-Key header. Use this for issuer and verifier admin operations.
• Bearer JWT — An access token sent in the Authorization header. Use this for Trust Registry DID operations and credential requests.
• DPoP (Demonstrating Proof-of-Possession) — A proof-of-possession mechanism (RFC 9449) that binds the access token to the client’s key pair, preventing token theft and replay. DPoP is per-token, not a deployment-wide flag — whether a given /credential request must use DPoP is decided by the issuer’s signing profile and the token type, not a global switch. Required by HAIP v1 (X.509 / ES256 issuers); optional on the EdDSA / DID path. See the endpoint mapping below.

Most discovery and protocol endpoints are public and require no authentication.

Rendering diagram...

---

1. API Key Authentication

curl -X POST https://issuer.turingspace.co/v1/offers \
  -H "X-API-Key: tcs_production_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4" \
  -H "Content-Type: application/json" \
  -d '{
    "credential": {
      "config_id": "TuringCerts_Standard_Credential_v2_sd_jwt",
      "claims": { "credentialName": "University Degree" }
    },
    "flow": "pre-authorized"
  }'

Send your API key in the X-API-Key header. You receive an API key when your organization is onboarded into the Trust Registry by the TCS team — there is no self-service apply endpoint; contact us to register. The server hashes your key with SHA-256 before storing it — the plaintext key is never persisted.

Detail	Value
Header	X-API-Key: {your_api_key}
Format	tcs_{environment}_{48-hex} (e.g., tcs_production_...)
Obtained from	Trust Registry onboarding (handled by the TCS team)
Storage	SHA-256 hash only; plaintext is not stored
Scope	Issuer admin operations, verifier admin operations

Endpoints Requiring API Key

Method	Endpoint	Service
POST	/v1/offers	Credential Issuer
POST	/v1/verifier/authorization-request	Verifier Service
GET	/v1/verifier/result/:sessionId	Verifier Service

Error Responses

Status	Message	Cause
401	API Key is required	Missing X-API-Key header
401	Invalid API Key	Key not found or hash mismatch
401	Account is not approved	Key is valid but the account is pending approval

---

2. Bearer JWT Authentication

# Trust Registry DID operation (token from login)
curl -X POST https://trust-registry.turingspace.co/v1/did \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..." \
  -H "Content-Type: application/json" \
  -d '{ "did": "did:key:z6Mk..." }'

# Credential request (token from token endpoint)
curl -X POST https://issuer.turingspace.co/credential \
  -H "Authorization: Bearer eyJhbGciOiJFUzI1NiJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "credential_configuration_id": "EmployeeCredential_sd_jwt",
    "proofs": {
      "jwt": ["eyJhbGciOiJFZERTQSIs...proof-jwt"]
    }
  }'

Send the access token in the Authorization: Bearer {token} header. There are two distinct JWT sources depending on the operation:

Purpose	Token Source	How to Obtain
Trust Registry DID operations	Login token	POST /v1/auth/login with uuid and password
Credential requests	Access token	POST /v1/token with pre-authorized code

Endpoints Requiring Bearer JWT

Method	Endpoint	Service	Token Source
POST	/v1/did	Trust Registry	Login token
POST	/v1/did/import	Trust Registry	Login token
POST	/credential	Credential Issuer	Token endpoint

Error Responses

Status	Message	Cause
401	invalid_token	Access token is invalid or expired
403	Forbidden	Account not approved for this operation

---

3. DPoP (Demonstrating Proof-of-Possession)

# Step 1: Create a DPoP proof JWT
# Header
{
  "typ": "dpop+jwt",
  "alg": "ES256",
  "jwk": { /* sender's public key */ }
}
# Payload
{
  "jti": "unique-id-abc123",
  "htm": "POST",
  "htu": "https://issuer.turingspace.co/credential",
  "iat": 1711411200,
  "ath": "fUHyO2r2Z3DZ53EsNrWBb0xWXoaNy59IiKCAqksmQEo"
}

# Step 2: Send both headers
curl -X POST https://issuer.turingspace.co/credential \
  -H "Authorization: DPoP eyJhbGciOiJFUzI1NiJ9..." \
  -H "DPoP: eyJ0eXAiOiJkcG9wK2p3dCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "credential_configuration_id": "EmployeeCredential_sd_jwt",
    "proofs": {
      "jwt": ["eyJhbGciOiJFZERTQSIs...proof-jwt"]
    }
  }'

DPoP (RFC 9449) binds the access token to the client’s key pair, so a stolen token cannot be used by another party. It is required by HAIP v1 and recommended for all credential endpoint interactions. Two headers are required: Authorization: DPoP {access_token} and DPoP: {proof_jwt}.

DPoP Proof JWT Structure

Header:

Field	Value	Description
typ	dpop+jwt	Fixed type for DPoP proofs
alg	ES256 or EdDSA	Signing algorithm
jwk	{ ... }	Sender’s public key in JWK format

Payload:

Field	Required	Description
jti	Yes	Unique identifier for replay protection
htm	Yes	HTTP method of the request (e.g., POST)
htu	Yes	HTTP URL of the request (without query/fragment)
iat	Yes	Issued-at timestamp (seconds since epoch)
ath	Yes	Base64url-encoded SHA-256 hash of the access token
nonce	Conditional	Server-provided nonce, required after receiving DPoP-Nonce header

Validation Parameters

Parameter	Value
Supported algorithms	EdDSA, ES256
Nonce expiry	300 seconds
JTI expiry	300 seconds
IAT max age	300 seconds
Clock skew tolerance	60 seconds (future)

DPoP Nonce Flow

When the server requires a nonce, it follows this exchange:

Rendering diagram...

1. Send your request with a DPoP proof that has no nonce field.
2. The server returns HTTP 400 with error use_dpop_nonce and a DPoP-Nonce response header.
3. Rebuild your DPoP proof JWT with the nonce field set to the value from the DPoP-Nonce header.
4. Retry the request with the updated DPoP proof.

Error Responses

Status	Error Code	Cause
400	invalid_dpop_proof	DPoP proof structure, signature, or ath validation failed
400	use_dpop_nonce	Server requires a DPoP nonce — check the DPoP-Nonce response header

---

4. Public Endpoints (No Authentication)

These endpoints require no authentication. They serve discovery metadata, protocol exchanges, and public registration.

Method	Endpoint	Service
GET	/v1/offers/:offerId	Credential Issuer
GET	/.well-known/openid-credential-issuer/:tenant	Credential Issuer
GET	/.well-known/oauth-authorization-server	Authorization Server
POST	/v1/token	Authorization Server
POST	/v1/nonce	Credential Issuer
POST	/v1/par	Authorization Server
GET	/v1/authorize	Authorization Server
POST	/v1/authorize/submit	Authorization Server
GET	/v1/verifier/request/:requestUriId	Verifier Service
POST	/v1/verifier/presentation	Verifier Service
GET	/schemas/:type/:version	Schema Registry
POST	/v1/auth/login	Trust Registry
GET	/.well-known/did-configuration.json/:tenant	Trust Registry

---

Complete Endpoint-to-Auth Mapping

Method	Path	Auth Type	DPoP required when	Service
POST	/v1/offers	API Key	—	Credential Issuer
GET	/v1/offers/:offerId	Public	—	Credential Issuer
POST	/credential	Bearer JWT or DPoP-bound	Issuer registered on the HAIP / X.509 / ES256 path; optional on the EdDSA / DID path	Credential Issuer
GET	/.well-known/openid-credential-issuer/:tenant	Public	—	Credential Issuer
GET	/.well-known/oauth-authorization-server	Public	—	Authorization Server
POST	/v1/token	Public	DPoP proof required to mint a DPoP-bound access token (HAIP path)	Authorization Server
POST	/v1/nonce	Public	—	Credential Issuer
POST	/v1/par	Public	—	Authorization Server
GET	/v1/authorize	Public	—	Authorization Server
POST	/v1/authorize/submit	Public	—	Authorization Server
POST	/v1/verifier/authorization-request	API Key	—	Verifier Service
GET	/v1/verifier/result/:sessionId	API Key	—	Verifier Service
GET	/v1/verifier/request/:requestUriId	Public	—	Verifier Service
POST	/v1/verifier/presentation	Public	—	Verifier Service
GET	/schemas/:type/:version	Public	—	Schema Registry
POST	/v1/auth/login	Public	—	Trust Registry
POST	/v1/did	Bearer JWT	—	Trust Registry
POST	/v1/did/import	Bearer JWT	—	Trust Registry
GET	/.well-known/did-configuration.json/:tenant	Public	—	Trust Registry

---

Common Error Codes

Status	Error	Description
400	invalid_grant	Pre-authorized code is expired or has already been used
400	invalid_dpop_proof	DPoP proof structure, signature, or ath validation failed
400	use_dpop_nonce	Server requires a DPoP nonce — check the DPoP-Nonce response header
401	invalid_token	Access token is invalid or expired
401	invalid_token (DPoP path)	Token is structurally valid but the endpoint requires DPoP binding — the issuer is registered on the HAIP / X.509 / ES256 path. Re-request with Authorization: DPoP <token> plus a DPoP: proof header (see §3).
401	API Key is required	Missing X-API-Key header
401	Invalid API Key	API key not found or hash mismatch
401	Account is not approved	API key is valid but the account is pending approval
403	Forbidden	Account not approved for this operation

---

What’s Next

• Issuing Credentials — Use your API key to create credential offers
• Verifying Credentials — Set up credential verification
• Trust & Schema Governance — Register and get your API key