Skip to content
Last updated

Quickstart

Get your first authenticated call working in a few minutes.

1. Provision a service user

Authentication is delegated to DeepCloud's IdP (Keycloak) — there is no DeepCredentials portal step to mint credentials. Before continuing, you need:

  • A partner client (Partner-Service-Client-ID + Partner-Service-Client-Secret) — request one from development@deepcloud.swiss.
  • A service user under that partner client, authorized by the owner of the end-client organization you want to act on. You receive a service_account_username + service_account_password per end client.
  • The organization UUID (X-Org-Id) the service user is a member of.

Full walkthrough: Authentication — Service Users.

2. Get an access token

Exchange the credentials for a Bearer JWT against the DeepCloud SSO realm. Test environment uses int.deepcloud.swiss; production uses deepcloud.swiss.

curl -X POST "https://deepcloud.swiss/auth/realms/sso/protocol/openid-connect/token" \
  --data-urlencode "grant_type=password" \
  --data-urlencode "username=<service_account_username>" \
  --data-urlencode "password=<service_account_password>" \
  --data-urlencode "client_id=<Partner-Service-Client-ID>" \
  --data-urlencode "client_secret=<Partner-Service-Client-Secret>" \
  --data-urlencode "scope=deepcredentials.verify"

Scope depends on the pillar you use. Use deepcredentials.verify for verification, deepcredentials.issue for issuance, and deepcredentials.self-service for self-service. Pass multiple scopes space-separated — for example scope=deepcredentials.verify deepcredentials.issue — if your integration spans more than one pillar.

The response includes access_token (valid 15 min) and refresh_token. Cache the access token and reuse until near expiry.

3. Call the health endpoint

Confirm your token works against the API:

Open in API reference →

curl -i -X GET \
  https://api.dev.deepcredentials.swiss/b2b/v1/health \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'X-Environment: beta' \
  -H 'X-Org-Id: 497f6eca-6276-4993-bfeb-53cbbbba6f08'

Every B2B request needs three headers:

HeaderValue
AuthorizationBearer <access_token>
X-Org-IdUUID of the organization the call acts on
X-Environmentbeta or production

Response

environmentstringrequired

Environment scoping the call (from X-Environment).

labelstringrequired

Human-readable label sourced from the JWT (e.g. preferred_username for service accounts).

org_idstring, (uuid)required

UUID v4 identifier.

Example:"550e8400-e29b-41d4-a716-446655440000"
scopesArray of stringsrequired

Scopes granted to this service user (from the JWT scope claim).

service_user_idstring, (uuid)required

UUID v4 identifier.

Example:"550e8400-e29b-41d4-a716-446655440000"
statusstringrequired

Always "ok" when the request is authenticated.

timestampstringrequired

Response time in RFC3339 UTC (for client logging and skew checks).

You're ready. Your credentials are valid and your integration can reach the API.

Next steps

Overview