All requests to the GeoSwift Platform REST APIs must be authenticated using a multi-factor security model that combines application identity verification, scoped authorization, and cryptographically signed requests.

To make an API call:

Identify your application using your issued Client ID and API Key.

Obtain a short-lived access token by exchanging your credentials via the token endpoint. This token includes permissions (scopes) that define what actions you’re authorized to perform.

Sign every request with an HMAC-SHA256 signature derived from your secret key, ensuring the request hasn’t been altered in transit and isn’t being replayed.

You can find your Client ID, API Key, and Secret Key in the GeoSwift Partner Dashboard under API Credentials.

All requests to the GeoSwift API must be authenticated using a three-layer security model that enforces:

Application identity verification,

Scoped authorization, and

Cryptographically verified request integrity with anti-replay protection.

This layered approach adheres to established industry best practices for financial-grade APIs, ensuring robust security, regulatory compliance, and resilience against credential compromise, request tampering, and replay attacks.

🔐 Security Model Overview

Layer	Purpose	Mechanism
1. Application Identity	Verifies which registered application is initiating the request	`GS-API-Key` + `GS-Client-ID`
2. Scoped Authorization	Grants least-privilege access based on pre-approved permissions	Short-lived OAuth 2.0 Bearer Token with explicit scopes
3. Request Integrity & Anti-Replay	Guarantees the request has not been altered or replayed	HMAC-SHA256 signature over critical request components, combined with timestamp and nonce

✅ All three layers are mandatory for all write operations (e.g., creating transactions). Read operations may optionally relax Layer 3 in low-risk environments, but full enforcement is strongly recommended in production.

🔑 Step 1: Obtain an Access Token

Before invoking any business endpoint, obtain a scoped access token using your issued credentials.

Endpoint

Headers

Header	Required	Example
`GS-API-Key`	Yes	`gs_live_abc123def456789`
`GS-Client-ID`	Yes	`partner_corp_xyz`
`Content-Type`	Yes	`application/json`

Request Body

{
  "grant_type": "client_credentials",
  "scope": "remittance:write verification:read"
}

💡 Supported Scopes (examples):
remittance:write
verification:read
transaction:read
webhook:manage

Response (200 OK)

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.xxxxx",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "remittance:write verification:read"
}

Step 2: Call a Business API

Include the token and cryptographic headers in all subsequent requests.

Example: Create a Remittance

Required Headers

Header	Description
`Authorization`	`Bearer <access_token>` obtained in Step 1
`GS-API-Key`	Your issued API key (must match the one used to obtain the token)
`GS-Timestamp`	Unix timestamp in seconds. Requests with `\|now - timestamp\| > 300` are rejected.
`GS-Nonce`	Random string (≥16 characters), unique per request
`GS-Signature`	Base64-encoded HMAC-SHA256 signature (see below)
`Idempotency-Key`	UUID v4. Required for all non-idempotent methods (`POST`, `PATCH`) to prevent duplicate processing

Step 3: Generate the Request Signature

To ensure end-to-end request integrity and prevent tampering, every request must include an HMAC-SHA256 signature in the GS-Signature header.

3.1 Signature Payload Construction

The signature payload is constructed by joining the following components with a pipe character (|) as a delimiter. Do not include trailing or leading pipes.

Payload Pattern:

HTTP_METHOD|URL_PATH|REQUEST_BODY|TIMESTAMP|NONCE

Components:

Component	Description	Example
`HTTP_METHOD`	Uppercase HTTP method	`POST`, `GET`, `PUT`, `DELETE`
`URL_PATH`	The request path (excluding domain and query parameters)	`/api/v1/payments`
`TIMESTAMP`	Must match the X-Timestamp header.	`1709123456`
`NONCE`	A unique random string for each request	`a1b2c3d4e5f6g7h8`
`REQUEST_BODY`	The raw request body string. Use empty string if no body	`{"name":"John"}`, `` (empty)

Important: The payload is case-sensitive. Ensure the REQUEST_BODY is the exact raw string being sent in the HTTP request (minify JSON to avoid whitespace discrepancies).

HMAC Algorithm (Java Example)

3.2 Handling the secretKey

The secretKey is a secret key that is used solely for signing API requests to ensure that the requests are authentic and have not been tampered with during transmission. It is never shared publicly and should be kept confidential.

Where to Obtain the secretKey

The secretKey is provided when you create your API credentials in the GeoSwift Partner Dashboard. It is a sensitive piece of information and should only be used in the backend of your application.

Storage of the secretKey

It should be stored securely in your backend system, using environment variables or a secrets management service (e.g., AWS Secrets Manager or HashiCorp Vault).

Use in Signing

The secretKey is used in the HMAC-SHA256 signing process, as shown in the example code above, to generate the signature. This ensures that the request's integrity is verified and that the request comes from an authorized source.

Common Error Responses

Status	Error Code	Message	Cause
`401 Unauthorized`	`INVALID_TOKEN`	`"Access token is missing, expired, or invalid"`	Invalid or missing `Authorization` header
`403 Forbidden`	`INSUFFICIENT_SCOPE`	`"Token lacks required scope: remittance:write"`	Token does not include necessary permission
`400 Bad Request`	`INVALID_SIGNATURE`	`"Request signature verification failed"`	HMAC mismatch due to tampering or incorrect secret
`400 Bad Request`	`TIMESTAMP_TOO_OLD`	`"Request timestamp exceeds allowed window (±300s)"`	Clock skew or replay attempt
`400 Bad Request`	`MISSING_IDEMPOTENCY_KEY`	`"Idempotency-Key is required for this operation"`	Omitted for state-changing request

Additional Security Controls

Transport Security: All endpoints require TLS 1.2 or higher.

Credential Rotation: API keys and secrets can be rotated via the Partner Dashboard without service interruption.

Network Restrictions: Partners may configure IP allowlists to restrict API access to known sources.

Webhook Verification: Incoming event notifications are signed using a dedicated webhook secret (separate from the API secret).

Auditability: Every request is logged with GS-API-Key, token scope, source IP, and timestamp for forensic analysis.

Authentication

🔐 Security Model Overview#

🔑 Step 1: Obtain an Access Token#

Endpoint#

Headers#

Request Body#

Response (200 OK)#

Step 2: Call a Business API#

Example: Create a Remittance#

Required Headers#

Step 3: Generate the Request Signature#

3.1 Signature Payload Construction#

HMAC Algorithm (Java Example)#

3.2 Handling the secretKey#

Common Error Responses#

Additional Security Controls#