Authentication & API Keys

Overview

Integrations authenticate with an API key. You create the key on the Skyline platform, exchange it for a short-lived access token, and refresh that token as it expires. Email and password login, two-factor authentication and password management are handled on the platform and are not part of an API integration.

Prerequisites

• Your account is approved and your organisation is active. See Account Setup.
• You have read the Getting Started guide for the base URL, request structure and error handling.

Integration User Requirements

Create the API key on a user that only your integration uses. That user must:

• Be dedicated to the integration. If a person logs in to the platform as the same user, the integration's refresh token stops working, and the other way round.
• Have the authorized member role in the organisation. Viewers can read, but cannot accept transactions or change receivers, bank accounts and organisation wallets. They get 401 Your user does not have enough permission to perform this action or 403 View-only members cannot modify beneficiaries.
• Have two-factor authentication turned off. The token exchange never asks for a code, so API sessions for a user with two-factor authentication on are locked out with 401 2FA session expired. Please login again.
• Have a confirmed account. Until the email address is confirmed, submitting and accepting transactions return 403 Account is not confirmed.
• Belong to an active organisation. Otherwise accepting a transaction returns 401 Organisation operational status does not permit this action.

The key acts in the user's selected organisation. A user that belongs to one organisation always has it selected.

Creating an API Key

Create the key on the Skyline platform under Settings → API connections. The platform shows a client ID and a secret. Store both securely: the secret is shown once and cannot be retrieved later.

Each user has one API key. Creating a new key replaces the previous one, and integrations still using the old secret will stop being able to obtain tokens. Use a dedicated integration user for server-side systems so that rotating the key never interferes with someone's personal access.

Exchanging the Key for Tokens

Send a POST request to /auth/token with the client ID and secret in the request body.

The response contains an access token and a refresh token. Include the access token in the Authorization header of every request:

Authorization: Bearer your-access-token

The access token is short-lived. The refresh token lives longer and is used to obtain a new pair without sending the secret again.

Refreshing Tokens

When the access token expires, send a POST request to /auth/refresh with the refresh token as the Bearer token in the Authorization header. The API returns a new access token and a new refresh token. Replace both stored values: the previous refresh token is no longer valid after the exchange.

Only one refresh token is valid per user at a time. If the same user obtains tokens from a second client, for example by logging in to the platform or calling the token endpoint again, the earlier refresh token is invalidated. Access tokens already issued keep working until they expire. When a refresh fails with a 401, exchange the key again with the token endpoint.

Revoking a Key

Revoke a key on the platform under Settings → API connections, or by sending a POST request to /auth/api-key/revoke with a valid Bearer token. After revocation the client ID and secret can no longer be exchanged for tokens. Access tokens already issued remain valid until they expire, so revoke early if a secret is compromised.

Endpoint Reference

What's Next

Continue with the Setup guide to register receivers, bank accounts and wallets before creating your first transaction.