Scaut Platform Authentication Documentation

Overview

The Scaut platform uses a multi-layered authentication system that provides secure identity verification and access control. This comprehensive documentation covers all authentication methods and security practices for developers integrating with our platform.

Key authentication mechanisms include:

1. User Authentication: Registration, sign-in, password management, and verification
2. JWT Tokens: Secure session management for API access
3. API Key Authentication: Long-lived tokens for server-to-server integration
4. WebAuthn (Passkey): Passwordless authentication using modern biometric and device-based security
5. Role-Based Access Control: Granular permissions through a robust role system

Authentication Basics

Authentication is a crucial aspect of using the Scaut platform. This guide will walk you through the authentication process.

User Authentication

1. Login: Enter your email and password on the login page.
2. Two-Factor Authentication (2FA): If enabled, enter the code sent to your mobile device.
3. Session Management: Stay logged in or log out as needed.

API Authentication

To authenticate API requests, include your API key in the request headers:

GET /api/resource
Host: api.scaut.com
Authorization: Bearer <YOUR_API_KEY>

Ensure that your API key is kept secure and not exposed in public repositories or client-side code.

1. User Authentication

1.1 Signup (Registration)

Endpoint:

POST /auth/signup
Content-Type: application/json

Description:

Creates a new user account with validation for all required fields. The provided password is securely hashed using modern secure algorithms.

Request Body:

{
  "email": "<unique_user_email>",
  "password": "<strong_password_placeholder>",
  "givenName": "<first_name_placeholder>",
  "familyName": "<last_name_placeholder>",
  "country": "<country_code>",
  "passkey": true,
  "compliance": true,
  "newsletters": false,
  "phone": "<phone_number_placeholder>"
}

Parameters:

• email (required): User's email address (valid format, max 64 chars)
• password (required): Password (min 8 chars, max 64 chars, with complexity requirements)
• givenName (required): User's first name
• familyName (required): User's last name
• country (required): ISO 3166-1 alpha-2 country code
• passkey (optional): Enable WebAuthn support
• compliance (optional): Accept terms and conditions
• newsletters (optional): Opt-in to newsletters
• phone (required): User's phone number

Response:

• On success: Returns the created user object (excluding sensitive data)
• On error: Returns appropriate error messages

Notes:

• A 6-digit verification code is generated and sent to the user's email
• The user account is initially disabled until verification is completed
• A demo organization is automatically created for the user

1.2 Account Verification

Endpoint:

POST /auth/verify
Content-Type: application/json

Description:

Verifies a user account using the code sent to their email address after registration.

Request Body:

{
  "code": "<dynamic_verification_code>"
}

Parameters:

• code (required): 6-digit verification code received by email

Response:

{
  "email": "<unique_user_email_identifier>",
  "accessToken": "<access_token_placeholder>",
  "refreshToken": "<refresh_token_placeholder>"
}

1.3 Signin (Login)

Endpoint:

POST /auth/signin
Content-Type: application/json

Description:

Authenticates a user with their email and password, issuing JWT access and refresh tokens upon success.

Request Body:

{
  "email": "<unique_login_identifier>",
  "password": "<secure_authentication_password>"
}

Parameters:

• email (required): User's email address
• password (required): User's password

Response:

{
  "email": "<unique_user_email_identifier>",
  "accessToken": "<access_token_placeholder>",
  "refreshToken": "<refresh_token_placeholder>"
}

1.4 Token Refresh

Endpoint:

POST /auth/refresh
Content-Type: application/json

Description:

Refreshes an expired JWT access token using a valid refresh token.

Request Body:

{
  "refreshToken": "<your_refresh_token>"
}

Parameters:

• refreshToken (required): A valid refresh token previously issued to the user

Response:

{
  "email": "<unique_user_email_identifier>",
  "accessToken": "<access_token_placeholder>",
  "refreshToken": "<refresh_token_placeholder>"
}

1.5 Password Management

1.5.1 Request Password Reset

Endpoint:

POST /auth/request-reset?email=<user_password_reset_identifier>

Description:

Initiates the password reset process by generating and sending a verification code to the user's email.

• email (required): Email address of the account

Response:

• Success message: "Please check your email"

1.5.2 Reset Password

Endpoint:

POST /auth/reset
Content-Type: application/json

Description:

Resets a user's password using the verification code they received.

Request Body:

{
  "password": "<new_secure_password>",
  "verify": <verification_code>
}

Parameters:

• password (required): New password (min 8 chars, max 64 chars)
• verify (required): 6-digit verification code received by email

Response:

• Success: Empty response with 200 status code
• Error: Appropriate error message

1.5.3 Change Password

Endpoint:

POST /auth/change-password
Content-Type: application/json
Authorization: Bearer <YOUR_ACCESS_TOKEN>

Description:

Allows an authenticated user to change their password by providing their current and new passwords.

Request Body:

{
  "userId": "<unique_user_identifier>",
  "currentPassword": "<current_password_placeholder>",
  "newPassword": "<new_password_placeholder>"
}

Parameters:

• userId (required): User's ID
• currentPassword (required): Current password
• newPassword (required): New password (min 8 chars, max 64 chars)

Response:

• Success: Empty response with 200 status code
• Error: Appropriate error message

1.6 Authentication Methods

Endpoint:

POST /auth/methods
Content-Type: application/json

Description:

Retrieves the available authentication methods for a specific user.

Request Body:

{
  "email": "<unique_user_email_identifier>"
}

Parameters:

• email (required): User's email address

Response:

{
  "email": "<unique_user_email_identifier>",
  "password": true,
  "passkey": true,
  "mfa": false
}

2. WebAuthn (Passkey) Authentication

The Scaut platform supports WebAuthn for passwordless authentication using biometrics, security keys, or platform authenticators.

2.1 Passkey Registration

2.1.1 Start Registration

Endpoint:

POST /auth/passkey/register-start
Content-Type: application/json

Description:

Initiates the WebAuthn registration process by generating a challenge and credential options.

Request Body:

{
  "username": "<webauthn_user_identifier>"
}

Parameters:

• username (required): User's email address

Response:

• Returns a PublicKeyCredentialCreationOptionsJSON object containing:
  • rpName: Relying party name (Scaut)
  • rpID: Relying party ID (domain)
  • userID, userName, userDisplayName: User information
  • attestationType: Set to "none"
  • authenticatorSelection: Options for the authenticator
  • supportedAlgorithmIDs: Supported cryptographic algorithms

2.1.2 Complete Registration

Endpoint:

POST /auth/passkey/register-end
Content-Type: application/json

Description:

Completes the WebAuthn registration by verifying the attestation response from the client.

Request Body:

{
  "username": "<webauthn_registration_identifier>",
  "data": {
    "id": "<dynamic_credential_key>",
    "rawId": "<randomized_base64_identifier_1>",
    "type": "public-key",
    "response": {
      "attestationObject": "<randomized_base64_identifier_2>",
      "clientDataJSON": "<randomized_base64_identifier_3>"
    }
  }
}

Parameters:

• username (required): User's email address
• data (required): WebAuthn credential data from the client

Response:

{
  "email": "<unique_user_email_identifier>",
  "accessToken": "<access_token_placeholder>",
  "refreshToken": "<refresh_token_placeholder>"
}

2.2 Passkey Login

2.2.1 Start Login

Endpoint:

POST /auth/passkey/login-start
Content-Type: application/json

Description:

Initiates the WebAuthn login process by generating a challenge for the user to sign.

Request Body:

{
  "username": "<webauthn_user_identifier>"
}

Parameters:

• username (required): User's email address

Response:

• Returns a PublicKeyCredentialRequestOptionsJSON object containing:
  • rpID: Relying party ID (domain)
  • allowCredentials: List of credentials the user can use
  • userVerification: Verification requirements
  • timeout: Time limit for the authentication process

2.2.2 Complete Login

Endpoint:

POST /auth/passkey/login-end
Content-Type: application/json

Description:

Completes the WebAuthn login by verifying the authentication response from the client.

Request Body:

{
  "username": "<webauthn_login_identifier>",
  "data": {
    "id": "<dynamic_login_credential_key>",
    "rawId": "<randomized_base64_login_identifier_1>",
    "type": "public-key",
    "response": {
      "signature": "<randomized_base64_login_identifier_2>",
      "authenticatorData": "<randomized_base64_login_identifier_3>",
      "userHandle": "<randomized_base64_login_identifier_4>",
      "clientDataJSON": "<randomized_base64_login_identifier_5>"
    }
  }
}

Parameters:

• username (required): User's email address
• data (required): WebAuthn authentication response from the client

Response:

{
  "email": "<unique_user_email_identifier>",
  "accessToken": "<access_token_placeholder>",
  "refreshToken": "<refresh_token_placeholder>"
}

3. API Authentication

3.1 JWT Authentication

After user authentication, use the JWT token in the Authorization header for subsequent requests:

GET /api/resource
Authorization: Bearer <your_access_token>

JWT tokens contain the following payload:

• Unique user identifier
• Authentication scopes
• Temporary access permissions

Tokens have a limited lifecycle and require periodic renewal to maintain secure access.

3.2 API Key Authentication

For server-to-server communication, API keys provide an alternative authentication method:

GET /api/resource
Host: api.scaut.com
Authorization: Bearer <YOUR_API_KEY>

Alternatively, you can use the "Api" prefix:

GET /api/resource
Authorization: Api <YOUR_API_KEY>

API key validation includes comprehensive security checks:

• Verification of key authenticity
• Enforcement of time-based access restrictions
• Validation of integration permissions
• Continuous monitoring of credential status

API keys should be kept secure and never exposed in client-side code or public repositories.

4. Authorization and Access Control

4.1 AuthGuard Service

The AuthGuard service protects API endpoints by:

1. Checking public access flags to bypass authentication for public endpoints
2. Extracting the token from request headers (or connection parameters for WebSockets/GraphQL)
3. Validating the token based on its type (Bearer JWT or API key)
4. Retrieving the user data, including roles and organization membership
5. Validating that the user has the required permissions for the requested operation

4.2 Organization Context

Most API endpoints require an organization context, specified through the orgId parameter. User permissions are evaluated within this organizational context, ensuring proper separation of data and access controls.

5. Security Considerations

5.1 Token Security

• Store JWT tokens securely (HTTP-only cookies for web applications)
• Do not store tokens in localStorage or sessionStorage
• Implement proper token refresh mechanisms
• Validate tokens on the server for every protected request

5.2 API Key Security

• Generate a unique API key for each integration
• Store API keys securely, never in client-side code
• Set appropriate expiration dates for API keys
• Limit API key permissions to only what is necessary
• Rotate API keys periodically

5.3 Password Security

• Use strong, unique passwords (minimum 8 characters)
• Implement proper password reset flows
• Never send passwords via email
• Store passwords using industry-standard secure hashing methods.

6. Error Handling

The API returns appropriate HTTP status codes and error messages:

• 400 Bad Request: Invalid input parameters
• 401 Unauthorized: Authentication failure (invalid credentials, expired token)
• 403 Forbidden: Insufficient permissions
• 404 Not Found: Resource not found
• 500 Internal Server Error: Server-side error

Example error response:

{
  "message": "<authentication_error_description>",
  "error": "<error_classification>",
  "statusCode": <standard_error_code>
}