Authentication & API Keys

Overview

This tutorial walks through every authentication workflow available in the Skyline Digital API: registering a new account, logging in with email and password, setting up two-factor authentication, refreshing tokens, creating API keys for machine-to-machine access, and managing credentials.

By the end of this guide you will understand how to obtain and maintain access to all authenticated API endpoints.

Prerequisites

Before starting this tutorial, make sure you have read the Getting Started guide, which covers the API base URL, request structure, and authentication concepts.

User Registration

To begin using the API, you first need to create a user account. Registration requires four fields:

Send these fields to the registration endpoint using a POST request to /auth/register.

After submitting the registration, the API sends a confirmation email to the address you provided. The email contains a verification link with a token. To activate your account, submit that token to /auth/confirm-account via a POST request. Until the account is confirmed, you will not be able to log in.

Logging In

Once your account is confirmed, you can authenticate by sending your email and password to /auth/login via a POST request.

On success, the API returns two tokens:

Store both tokens securely. The access token should be included in the Authorization header of every subsequent API request.

Two-Factor Authentication

If two-factor authentication (2FA) is enabled on the platform, the login response includes a flag indicating that 2FA setup is required. The flow works as follows:

Initial Setup

When you log in for the first time with 2FA enabled, the response includes a temporary token and a field indicating that 2FA setup is required. You then proceed through two steps:

1. Generate a 2FA secret. Send a POST request to /auth/2fa/generate using your temporary token. The API returns a secret and a provisioning URI that you can use with any standard authenticator application (such as Google Authenticator or Authy) to generate time-based one-time passwords.

2. Verify your 2FA setup. Enter the six-digit code from your authenticator application and send it to /auth/2fa/verify via a POST request. This confirms that your authenticator is correctly configured and enables 2FA for your account.

Subsequent Logins with 2FA

Once 2FA is enabled, the standard login endpoint returns a temporary token instead of the full access and refresh token pair. To complete authentication:

Send a POST request to /auth/2fa/login with the temporary token and the current six-digit code from your authenticator application. On success, the API returns the full access token and refresh token pair.

Refreshing Tokens

Access tokens are short-lived by design. When your access token expires, use the refresh token to obtain a new pair without logging in again.

Send a POST request to /auth/refresh with the refresh token in the Authorization header as a Bearer token. The API returns a new access token and a new refresh token. Replace both stored tokens with the new values -- the previous refresh token is no longer valid after this exchange.

If the refresh token itself has expired or been invalidated, you need to log in again with your email and password.

API Key Authentication

API keys provide machine-to-machine access for server-side integrations, automated workflows, and background services. Unlike JWT tokens obtained through email and password login, API keys do not require interactive user authentication.

Creating an API Key

To create an API key, you must first be authenticated with a JWT token (obtained through the login flow described above). Send a POST request to /auth/api-key with your Bearer token in the Authorization header.

The API returns a client ID and a secret. Store these credentials securely -- the secret is only shown once and cannot be retrieved later.

Using an API Key to Obtain Tokens

Once you have a client ID and secret, exchange them for access tokens by sending a POST request to /auth/token with the client ID and secret in the request body.

The API returns an access token and a refresh token, just like the login flow. Use the access token in the Authorization header for subsequent API requests.

Revoking an API Key

If an API key is compromised or no longer needed, revoke it by sending a POST request to /auth/api-key/revoke with your JWT Bearer token in the Authorization header. This immediately invalidates the API key, and any tokens obtained through it can no longer be refreshed.

Logging Out

To end your session and invalidate your current access token, send a POST request to /auth/logout with your Bearer token in the Authorization header. After logging out, both the access token and refresh token associated with the session are invalidated.

Password Management

The API provides three password-related operations:

Changing Your Password

If you know your current password and want to change it, send a POST request to /auth/change-password with your current password and new password. This requires an active JWT session (Bearer token in the Authorization header).

Forgot Password

If you have forgotten your password, send a POST request to /auth/forgot-password with your email address. This is a public endpoint that does not require authentication. The API sends a password reset email containing a reset token.

Resetting Your Password

After receiving the password reset email, send a POST request to /auth/reset-password with the reset token from the email and your new password. This is also a public endpoint. Once the password is reset, you can log in with your new credentials.

Endpoint Reference

The table below summarises all authentication endpoints covered in this tutorial.

What's Next

With authentication in place, the next step is to set up your organisation and complete identity verification. Proceed to the KYC and KYB Verification tutorial to learn how to create an organisation, complete identity checks, and unlock the full platform.