Authentication

The Apicunia API Suite supports secure API access using one of the following authentication methods:

• OAuth 2.0
• Mutual TLS (mTLS) using PSD2 QWAC certificates

All API requests must be authenticated before access is granted. Make all API requests over HTTPS. Calls made over plain HTTP will fail.

---

Supported Authentication Methods

Method	Recommended For
OAuth 2.0	Non-Regulated PISP API integrations and delegated access
mTLS with PSD2NAN QWAC	Regulated financial institutions and PSD2/Open Banking integrations

---

OAuth 2.0 Authentication

OAuth 2.0 allows clients to securely authenticate and obtain access tokens for API access.

OAuth Flow

The API uses the Client Credentials Grant flow.

Token Endpoint

GET https://login.microsoftonline.com/{YOUR_TENANT_ID}/oauth2/v2.0/token

---

Request Example

bash

curl --location --request GET 'https://login.microsoftonline.com/{YOUR_TENANT_ID}/oauth2/v2.0/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id={YOUR_CLIENT_ID}' \
--data-urlencode 'client_secret={YOUR_CLIENT_SECRET}' \
--data-urlencode 'scope={YOUR_SCOPE_ID}/.default'

Response Example

json

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Using the Access Token

Include the access token in the Authorization header for all API requests.

Authorization: Bearer YOUR_ACCESS_TOKEN

---

Token Expiry

Access tokens expire after a limited period of 1 hour (3600 seconds). When a token expires, clients must request a new token from the token endpoint. The Client Credential flow does not issue a refresh token, you must request a new access token when the current token expires.

---

Mutual TLS (mTLS)

The Payee Verification API Suite supports mutual TLS authentication for regulated financial entities and secure machine-to-machine communication.

mTLS authentication requires:

• A valid PSD2 QWAC certificate
• TLS client certificate presentation during the TLS handshake
• Approved onboarding with the platform

---

PSD2 QWAC Requirements

Supported certificates must:

• Be issued by a qualified trust service provider (QTSP)
• Comply with PSD2 requirements
• Include PSD2 roles where applicable
• Be valid and non-expired

Example supported certificate types:

• PSD2NAN QWAC

---

TLS Handshake Authentication

During connection establishment:

1. The client presents its QWAC certificate
2. The certificate is validated
3. The TLS session is established
4. API access is granted if validation succeeds

Connections without a valid certificate will be rejected.

---

Example mTLS Request

curl --request POST \
  --url https://api.apicunia.com/vop/v1/payee-verifications \
  --cert client-cert.pem \
  --key client-key.pem \
  --header "Content-Type: application/json" \
  --data '{
  "party": {
    "name": "Lukas Klein"
  },
  "partyAccount": {
    "iban": "DE33500105175746121394"
  },
  "partyAgent": {
    "financialInstitutionId": {
      "bicfi": "INGDDEFFXXX"
    }
  },
  "unstructuredRemittanceInformation": [],
  "requestingAgent": {
    "financialInstitutionId": {
      "bicfi": "AGRIFRPP888"
    }
  }
}'

---

Certificate Management

Certificate Rotation

Clients are responsible for rotating certificates before expiration.

Expired certificates will fail authentication.

---

Revocation Handling

Revoked certificates are automatically denied access.

Clients should immediately replace compromised certificates.

---

Authentication Errors

Status Code	Meaning
401	Authentication failed
403	Certificate or token not authorised

---

Security Recommendations

We recommend the following security practices:

• Store credentials securely
• Rotate secrets and certificates regularly
• Use least-privilege access
• Never expose credentials in frontend applications
• Restrict API access to trusted environments
• Monitor authentication activity

TLS Requirements

All connections to Apicunia APIs must use TLS 1.2 or later.

Clients must negotiate a supported TLS version and cipher suite when establishing a connection to an API. Connections using unsupported TLS versions or cipher suites will not be accepted.

Recommendation

Clients should use TLS 1.3 where supported.

For specific information on which TLS cipher suites are supported, please see the Security section within the documentation for each individual API.

---

Sandbox Authentication

The sandbox environment supports both OAuth 2.0 and mTLS testing.

Sandbox Base URL(s):

https://test-apigw.apicunia.com
https://test-api.apicunia.com

Sandbox credentials and test certificates are separate from production credentials.

---

Production Access

Production API access requires:

1. Successful onboarding through our sandbox
2. Credential issuance
3. Certificate validation (for mTLS integrations)
4. Security review approval where applicable

---

Need Help?

For onboarding assistance or authentication support, contact:

support@apicunia.com