Making authenticated requests

This guide explains how to authenticate with the AdmiralCloud platform and make secure API requests to protected resources.

Authentication Methods

AdmiralCloud supports two primary authentication methods:

1. Browser-based Authentication – Using OAuth2 for interactive web applications
2. Server-to-Server Authentication – Using API keys for backend services

OAuth2 Browser-based Authentication

All browser-based applications must implement the OAuth2 authorization code flow as defined in RFC 6749.

Required Authentication Headers

Every authenticated request should include three HTTP headers:

Header	Format	Required	Description
x-admiralcloud-clientid	String	yes	Your application’s unique client ID
x-admiralcloud-device	String	no	Unique device identifier
Authorization	Bearer {token}	yes	Access token obtained from the auth flow

Authentication Process

Prerequisites

1. Client ID: Obtain your client ID from the AdmiralCloud engineering team
2. Device Identifier: Generate a unique identifier for each user-device combination
3. Redirect URI: Register your application’s callback URL with AdmiralCloud

Please note: If you use a device identifier (recommended) you have to use it with every call – the session will be bound to that identifier.

Step-by-Step OAuth2 Flow

1. Initiate Authorization:

GET https://auth.admiralcloud.com/v4/authorize?
client_id={YOUR_CLIENT_ID}&
response_type=code&
redirect_uri={YOUR_CALLBACK_URL}&
state={RANDOM_STATE_VALUE}&
device={DEVICE_IDENTIFIER}

2. User Authentication:

• The Auth Server redirects to the login page if no valid session exists
• The user enters credentials or authenticates via SSO
• Upon successful login, the Auth Server generates an authorization code and redirects to the redirect_uri from “Initiate Authorization”. The response contains the code

3. Exchange code for token

// in your client app
POST https://auth.admiralcloud.com/v4/token
{
  "grant_type": "authorization_code",
  "code": "AUTH_CODE_HERE",
  "redirect_uri": "https://app.example.com/callback",
  "client_id": "ae744902-efb2-448a-919d-18b27212aa86",
  "device": "unique-device-identifier"
}

4. Use the token

GET https://iam.admiralcloud.com/v2/me
Authorization: Bearer eyJhbGciOiJIUzI1...
x-admiralcloud-clientid: YOUR_CLIENT_ID
x-admiralcloud-device: DEVICE_IDENTIFIER

Server-to-Server Authentication

AdmiralCloud supports a secure method for server-to-server communication using cryptographically signed requests. This method is ideal for automated processes and backend integrations.

Overview

This authentication method uses requests signed with a cryptographic hash generated from the payload, path, and a shared secret (Access Secret). This ensures:

1. The request originates from an authorized system (authenticity)
2. The content hasn’t been tampered with during transmission (integrity)
3. The request occurs within a specific timeframe (protection against replay attacks)

Prerequisites

• Access Key: Your unique client identifier for the API
• Access Secret: Your private key used to generate signatures (never share this)

Contact support@admiralcloud.com to obtain these credentials.

How It Works

1. For each API request, you generate a signature using your Access Secret, request path, and payload
2. The signature is included in the request headers along with your Access Key and a timestamp
3. The server validates the signature using your Access Secret to ensure the request is authentic

Implementation

AdmiralCloud provides libraries to simplify signature generation:

• NodeJS: https://github.com/admiralCloud/ac-signature
• PHP: https://github.com/AdmiralCloud/ac-signature-php
• Java: https://github.com/AdmiralCloud/ac-signature-java

Those package also contain examples.