Clearstream Authentication

specification: API Commons Authentication
specificationVersion: '0.1'
provider: Clearstream
providerId: clearstream
generated: '2026-09-05'
modified: '2026-09-05'
method: searched
source: >-
  Clearstream API Developer Guide (Clearstream Banking S.A., August 2025) —
  https://www.clearstream.com/caas/v1/media/2934048/data/3fa3fec668d8dd198e9bed4df879b26b/api-developer-guide.pdf
  (HTTP 200, application/pdf), plus live unauthenticated probes of the Clearstream API
  Platform pre-production host https://api-t2s-test.clearstream.com (HTTP 403 JSON envelopes
  naming the required scopes) on 2026-09-05.
docs:
  - https://www.clearstream.com/clearstream-en/res-library/connectivity/clearstream-api-services-2916788
  - https://www.clearstream.com/caas/v1/media/2934048/data/3fa3fec668d8dd198e9bed4df879b26b/api-developer-guide.pdf
  - https://docs.developer.deutsche-boerse.com/docs/consumer/mTLS-consumer
description: >-
  Authentication profile for the Clearstream API Platform (api.clearstream.com). Clearstream
  runs an OAuth 2.0 resource-owner password-credentials flow that it has hardened by requiring
  a mutual-TLS connection on every call — both to the token endpoint and to every resource
  endpoint. Credentials are not self-service: an API consumer is a technical user created
  inside the Xact Web Portal, and the X.509 client certificate and key are generated in the
  browser during that user's creation. This profile is read from Clearstream's own published
  developer guide and confirmed against live 403 responses; no OpenAPI securitySchemes block
  exists because Clearstream publishes its OpenAPI only inside the registration-gated Deutsche
  Börse Digital Business Platform catalogue.
schemes:
  - id: oauth2-password-mtls
    type: oauth2
    flow: password
    label: OAuth 2.0 resource owner password credentials, over mutual TLS
    token_endpoint: https://api.clearstream.com/authmanager/oauth2/access_token
    token_endpoint_test: https://api-t2s-test.clearstream.com/authmanager/oauth2/access_token
    grant_type: password
    request_encoding: application/x-www-form-urlencoded
    request_parameters:
      - name: grant_type
        value: password
        required: true
      - name: scope
        required: true
        note: >-
          Space separated. The literal scope `allow` is mandatory on every request and must be
          accompanied by at least one API-specific scope. Requesting an invalid scope returns a
          400 whose body lists the scopes valid for that consumer.
      - name: username
        required: true
        note: The Xact API Consumer user id, e.g. the form a00012345_0012345.
      - name: password
        required: true
        note: The API consumer login password set during Xact user creation.
    client_authentication: none
    client_authentication_note: >-
      No OAuth 2.0 client_id / client_secret basic-auth header is required — Clearstream
      identifies the client from the mutual-TLS certificate plus the consumer password sent as
      form data. The guide states that a basic-auth header set to any placeholder value is
      accepted and ignored, for libraries that insist on sending one.
    response:
      access_token: JWT bearer token
      refresh_token: issued
      token_type: Bearer
      expires_in: 3599
      scope: echoed back as the granted scope string
    resource_usage: 'Authorization: Bearer ${ACCESS_TOKEN}'
  - id: mutual-tls
    type: mutualTLS
    label: Mandatory mutual TLS (X.509 client certificate)
    scope_of_application: >-
      Every call to the Clearstream API Platform, including the OAuth token endpoint. Running
      without a proper CA chain or truststore ("insecure mode") is explicitly unsupported.
    client_certificate:
      issued_by: Clearstream, during Xact Web Portal API Consumer creation
      delivery: >-
        Two PEM files are generated and downloaded in the browser — a signing certificate/key
        pair and an SSL (TLS) certificate/key pair — named ocapi-{USERID}-{TYPE}.pem. The SSL
        file is the one used for the mutual-TLS connection.
      validity: 2 years; expiry visible to Xact OU administrators in the credential details screen
      binding: >-
        The client certificate Common Name (CN) must match the Xact user id carried in the
        OAuth 2.0 token subject. Observed verbatim in the live 403 body from
        https://api-t2s-test.clearstream.com/playground/v1/info on 2026-09-05.
    server_trust:
      root_ca: DigiCert Global Root G2
      note: >-
        Clients must add the server CA chain to their truststore. Certificate pinning is
        explicitly unsupported, and Clearstream reserves the right to rotate API server
        certificates with no prior announcement.
    client_ca_bundle: https://api.clearstream.com/client-cert-cacerts.pem
authorization:
  model: >-
    Two layers. Coarse-grained access is the set of Clearstream API resources granted to the
    Xact Organisation Unit and then to the individual API Consumer user; that grant is what
    determines which OAuth scopes the token server will issue. Fine-grained access is a
    per-API role model inside Xact — for example most User Management (SCIM2) calls additionally
    require the SCIM Admin or SCIM Read-Only role on top of the Xact Web Portal User Management
    API role.
  onboarding_channel: >-
    Existing Xact clients enable the service by sending an MT599 SWIFT message to
    CEDELULLXXX (attn. PRGConnect) naming the API resources to link to their Organisation Unit.
    Prospects contact the Clearstream Connectivity Helpdesk at connect@clearstream.com.
  self_service: false
errors:
  invalid_scope: 400 — response body enumerates the scopes valid for the consumer
  wrong_parameter: 403 Forbidden from the authorisation server; cause visible only in the Xact OU audit log
  wrong_host: >-
    OAuth requests sent to https://xact.clearstream.com are rejected; the token endpoint is on
    https://api.clearstream.com (or the matching test host).
observations:
  - fetched: '2026-09-05'
    url: https://api-t2s-test.clearstream.com/playground/v1/info
    http_status: 403
    content_type: application/json; charset=utf-8
    note: >-
      Unauthenticated probe. Body names the mandatory `allow` scope, the API scope
      `ocapi-playground-v1`, and the certificate-CN-to-token-subject binding rule.
  - fetched: '2026-09-05'
    url: https://api.clearstream.com/
    http_status: 503
    note: >-
      The production API host was serving a "Scheduled Maintenance" page for every path at the
      time of this pass, so production probes could not be completed; the pre-production host
      api-t2s-test.clearstream.com was up and answered.
maintainers:
  - FN: Kin Lane
    email: kin@apievangelist.com