Authentication and authorisation

Every call on this portal needs a bearer token. The only operations you can reach without one are the security token service's own five, and they authenticate with your client secret in the request body instead.

Getting a token

The security token service publishes four endpoints and a health probe, all of them POST and all of them JSON.

POST /sts/api/token exchanges credentials for tokens. It returns access_token, token_type, expires_in, scope and, depending on the grant, refresh_token.

POST /sts/api/authorize is the authorisation endpoint, returning code, redirect_uri and state for the flows that need a browser redirect.

POST /sts/api/revoke and POST /sts/api/introspect take a token plus your client id and secret: the first invalidates it, the second reports whether it is still active and what scope, exp and client_id it carries.

The token endpoint accepts fields for several grant types in one request shape, and which of them you send is what selects the flow:

For a bank integrating server to server, client credentials is the flow. The portal's own try-it panel uses it, and so should your service.

One thing to know before you write the client

Send every field exactly as the specification spells it, and read the spelling off the specification rather than off the RFC. This portal does not correct field names silently: a name that is wrong upstream is wrong on the wire, and finding that out from a 400 in integration testing costs a day. The PKCE parameter is the case that taught this — it was published as code_challange, was corrected to code_challenge upstream, and a client written against either sentence alone was wrong for part of the year.

What a token is worth

An access token is a bearer credential. Anyone holding it can do what it permits, so:

• Keep it server-side. The portal proxies its own try-it requests through the server for this reason — the token would otherwise have to be in the page.
• Cache it until it expires, then get another. Do not request one per call. Honour expires_in rather than assuming a lifetime, and refresh slightly early so a call does not fail on a token that expired in flight.
• Treat a 401 as "get a new token and retry once". Not as a loop. The portal itself retries exactly once and then reports the failure.

User management

Drafted from the framework reference.

The platform separates two things a single "user" concept usually confuses:

A client is a system. It holds a client id and secret, it authenticates with client credentials, and it is what your integration is. Clients are provisioned by DgPays, per environment, and a sandbox client is not a production client.

A user is a person operating the back office — an agent, a supervisor, an administrator. Users hold roles, roles hold permissions, and every action a user takes is recorded against them.

You do not manage users through the APIs on this portal. Card operations performed on a cardholder's behalf carry a channel and a reference, not an operator identity, which is why the call-centre capability is listed as planned: the operations exist but nothing on them carries who made the call.

Roles and access management

Drafted from the framework reference.

Back-office changes that matter run through maker-checker: the person who makes a change cannot be the person who approves it, and the change does not take effect until a second role does. This applies to configuration, limits policy and reference data — the things where a single mistaken edit reaches every card at once.

For an integrating bank the consequence is practical: a configuration change you request is not immediate. It is made, then approved, and both steps are recorded. Build that into your go-live plan rather than discovering it during certification.

Single sign-on

Drafted from the framework reference. This installation's provider is not confirmed.

The back office supports federated sign-in so a bank's own staff use their own directory rather than a second set of credentials. What is not yet settled is which provider fronts it here, whether a bank federates its own tenant, and how roles map across the federation — a bank's "supervisor" and the platform's "supervisor" are not automatically the same permission set.

These are the questions to put on the table in the programme design phase, not at certification. They are listed at the top of this page for that reason.

Field-level encryption

Sensitive values are encrypted at field level with a certificate held per environment, and stored with an ENC: prefix marking them. Fields that are not sensitive stay in the clear, so reading a configuration does not require decrypting all of it.

Two consequences for you:

• A value encrypted in the sandbox cannot be read in production. Test data does not migrate; it is recreated.
• A response carrying real card data is one of a small, named set of operations. Everything else returns a masked number, and the masked number is what is safe to store and to log.