Authentication

The Integration Hub enforces a layered security model for all communication between Toqio and financial provider integrations. The model is designed around the principle of defence in depth: each layer adds an independent security control, and layers are composable rather than mutually exclusive.

During the onboarding process, the integrator and Toqio jointly evaluate which combination of layers is appropriate given the specific integration scenario, regulatory context, and risk profile.

All communication between Toqio and the integration layer must be transmitted over HTTPS (TLS 1.2 minimum, TLS 1.3 recommended). Unencrypted HTTP connections are not accepted.

Layer 1 — API Key

API Key authentication is the baseline mechanism supported by all integrations. It applies to both outbound requests from Toqio to the integration, and inbound webhook calls from the integration to Toqio.

How it works

Toqio issues an API Key to the integrator during onboarding. The key is transmitted as an HTTP header on every request:

X-Api-Key: {your_api_key}

Inbound webhook calls from the integration to Toqio must include the API Key issued for that integration in the same header format.

Credential management

• API Keys are generated by Toqio and securely transmitted to the integrator during onboarding.
• Key rotation is supported. Rotation requests must be initiated through the established support channel. During rotation, a grace period is provided to avoid service interruption.
• API Keys must be stored securely and must never be embedded in client-side code or exposed in version control systems.

Layer 2 — HMAC Payload Signature

HMAC signature verification provides payload integrity and request authenticity on top of API Key authentication. It ensures that the payload received has not been tampered with in transit and that it originates from a trusted source.

How it works

Toqio signs every outbound request payload using HMAC-SHA256 with a shared secret derived during onboarding. The signature is included as an HTTP header:

X-Toqio-Signature: sha256={base64_encoded_hmac_signature}

The integrator computes the expected signature independently using the same shared secret and compares it against the received header value. Requests where the signature does not match should be rejected.

Signature computation:

HMAC-SHA256(secret, raw_request_body_as_bytes)

The signature is computed over the raw request body bytes, prior to any parsing. Using a parsed or reformatted body will produce a different signature.

Inbound webhooks from the integration to Toqio

The same mechanism applies in the reverse direction. Toqio validates the X-Toqio-Signature header on all inbound webhook calls. The shared secret used for signing inbound requests is established separately during onboarding and is independent from the outbound signing secret.

Handling signature validation failures

• Respond with HTTP 401 Unauthorized when the signature is absent.
• Respond with HTTP 403 Forbidden when the signature is present but invalid.
• Log the failure with sufficient context for audit purposes.
• Do not process the payload if signature validation fails.

Layer 3 — OAuth 2.0 / OIDC Client Credentials with Self-Signed JWT Bearer

For integrations requiring the highest level of authentication assurance, the Integration Hub supports OAuth 2.0 Client Credentials Grant with JWT Bearer token as defined in RFC 7523. This mechanism eliminates the transmission of shared secrets entirely, replacing them with asymmetric cryptography.

How it works

The integrator generates an asymmetric key pair (RSA 2048-bit minimum, or EC P-256/P-384). The public key is registered with Toqio during onboarding. The private key never leaves the integrator's infrastructure.

To authenticate, the integrator generates a self-signed JWT assertion using the private key and presents it to Toqio's token endpoint to obtain a short-lived access token:

JWT Assertion structure:

Header:
{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "{key_id_registered_with_toqio}"
}

Payload:
{
  "iss": "{client_id_assigned_by_toqio}",
  "sub": "{client_id_assigned_by_toqio}",
  "aud": "https://integrate.toq.io",
  "iat": {issued_at_unix_timestamp},
  "exp": {expiry_unix_timestamp},
  "jti": "{unique_jwt_id}"
}

Token request:

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
&assertion={signed_jwt}

Token response:

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

The access token is then included on every subsequent request:

Authorization: Bearer {access_token}

Key pair management

• Key pairs are generated and managed entirely by the integrator.
• Only the public key is shared with Toqio during onboarding or key rotation.
• Key rotation does not require downtime: register the new public key alongside the existing one, migrate traffic, then deregister the old key.
• The kid (Key ID) header in the JWT assertion identifies which registered public key Toqio should use for verification, enabling smooth key rotation with zero service interruption.

Token lifetime and refresh

• Access tokens have a default lifetime of 3600 seconds (1 hour).
• The integrator is responsible for proactively refreshing tokens before expiry.
• Toqio does not issue refresh tokens under the Client Credentials grant. A new assertion must be generated to obtain a new access token.

Mutual TLS (mTLS)

Mutual TLS provides authentication at the transport layer, requiring both parties to present valid X.509 certificates during the TLS handshake. This establishes cryptographic identity before any HTTP request is processed.

mTLS is available as a complementary transport-layer control and can be requested as part of the onboarding process. It is particularly relevant for integrations that operate under specific regulatory or contractual requirements that mandate transport-level mutual authentication.

Selecting the right approach

The appropriate combination of authentication layers depends on factors specific to each integration: the regulatory environment, the sensitivity of the financial operations involved, the operational capabilities of the integrator, and any security requirements mandated by the financial provider being connected.

During the onboarding process, Toqio and the integrator jointly assess these factors and agree on the authentication configuration for the integration. This ensures that the selected approach reflects the actual risk profile of the scenario rather than a generic default.