Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Authenticating to Your Deployment

Every One-Click Deployment ships with its own credential API — an Issuer API (OpenID4VCI) and a Verifier API (OpenID4VP) reachable at your deployment's base URL, for example https://example-name.evdi.app. Administrative operations on that API are protected, so you authenticate each request with an admin Bearer (JWT) token issued by your deployment's identity provider (Keycloak).

When you create a deployment, the portal shows your Keycloak access credentials once — the realm name, admin username and initial password, realm admin URL, and client ID (see Creating a Deployment). You use these to obtain the Bearer token, then present it in the standard HTTP Authorization header; the deployment validates it before running the operation. Without a valid token, administrative calls are rejected.

Obtaining a Token

Request an access token from your deployment's Keycloak realm using the account credentials shown when you created the deployment. The token endpoint follows the standard Keycloak path:

curl -X POST \
  https://keycloak.evdi.app/realms/<REALM_NAME>/protocol/openid-connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password" \
  -d "client_id=<CLIENT_ID>" \
  -d "username=<USERNAME>" \
  -d "password=<PASSWORD>"

Fill in the Realm Name, Client ID, Username, and Initial Password from the credentials screen, and use the Keycloak host from your Realm Admin URL. The response's access_token is the Bearer token you send to the deployment's API — it carries the admin role the API requires, and it expires, so request a fresh one when it lapses.

How Authentication Works

  • The deployment validates a signed OIDC JWT on every protected request. You pass the token as a Bearer credential in the Authorization header.

  • The token's signature is checked against the platform's identity provider. A valid token authorizes the credential operations on your deployment — managing schemas and credential offers, signing credentials, and creating authorization requests — and the admin role additionally gates the agent/DID and wallet-management endpoints.

  • There is no separate static API key or shared password on the API itself — the Bearer token obtained from your deployment's Keycloak is the only credential your client sends with each request.

Using the Token

Send the token in the Authorization header on every administrative request, prefixed with Bearer:

Example: Direct API Access

The example below assigns a credential schema to an Issuer by calling the deployed Issuer API directly. Replace the base URL with your deployment's fullHost, the path's :issuerDid with your Issuer's DID, and <YOUR_ACCESS_TOKEN> with the token you obtained above.

A successful response confirms the assignment:

The same Authorization: Bearer <token> header applies to every administrative endpoint — creating credential offers (for example, referencing the EmployeeBadge@1:sd-jwt configuration), signing credentials, and creating verification requests. The full set of paths, request bodies, and responses is documented in each deployment's interactive API reference, served at /api-docs (for example https://example-name.evdi.app/api-docs).

Rotating Credentials

If your credentials are ever exposed, or you want to rotate them on a schedule, sign in to your deployment's Keycloak admin console (the Realm Admin URL shown when you created the deployment) and reset the admin user's password there (the deployment uses a public Keycloak client, so there is no client secret to rotate).

After rotation, update every client, script, and integration to obtain and send a token minted with the new credentials right away.

Security Notes

  • Treat the token as a secret. Anyone holding it can perform administrative operations against your deployment. Store it in a secrets manager or environment variable — never commit it to source control or paste it into client-side code.

  • Always use HTTPS. Bearer tokens must only travel over TLS so the credential is never sent in clear text. Production deployments are served over HTTPS.

  • Send it server-to-server. Keep the token on your backend and call the deployment API from there; do not embed it in browsers, mobile apps, or other untrusted clients.

  • Rotate on exposure. If the credentials may have leaked, reset the admin user's password immediately in the Keycloak admin console (see above).

Next Steps

  • Issuer API — issue credentials with OpenID4VCI: schemas, credential offers, issuance sessions, and direct signing.

  • Verifier API — request and verify presentations with OpenID4VP: authorization requests, verification sessions, and direct verification.

Each deployment also exposes its own live API reference at /api-docs, where you can browse and try the exact endpoints your token unlocks.

PreviousVerifying CredentialsNextIssuer

Last updated