Authentication

Authentication

Overview

flaikConnect uses OAuth2 Client Credentials flow for secure, server-to-server authentication. This approach ensures that API access is properly authorized while maintaining the security standards required for handling sensitive employee and lesson data.

Why OAuth2 Client Credentials?

Business Context: Unlike user-facing authentication (where individuals log in), flaikConnect is designed for system-to-system integration. Your HRIS, reporting tools, or custom applications need to authenticate as trusted systems rather than individual users.

Technical Benefits:

• Secure: No user credentials stored in your applications

• Scalable: Single set of credentials for your entire integration

• Auditable: All API calls are traceable to your client application

• Time-limited: Tokens expire automatically for enhanced security

Getting Your Credentials

Your flaik representative will provide you with:

• Client ID: Public identifier for your application

• Client Secret: Private key for authentication (keep secure!)

• Auth URL: OAuth2 token endpoint for your environment

• API URL: Base URL for all API calls

• Scopes: Permissions granted to your integration

Example Scope Permissions

Scope	Access Level	Description
flaik.connect.api.read	Read Only	Retrieve data from all flaikConnect endpoints
flaik.connect.api.write	Read + Write	Full access including employee updates and data uploads

Your assigned scopes depend on your integration requirements and will be configured during setup.

Authentication Flow

1. Request an Access Token

Make a POST request to your OAuth2 token endpoint:

POST {auth-url}/connect/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic {base64(clientId:clientSecret)}

grant_type=client_credentials&scope={your-assigned-scopes}

2. Parse the Token Response

Successful authentication returns:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 600,
  "scope": "flaik.connect.api.read flaik.connect.api.write"
}

3. Use the Token for API Calls

Include the access token in the Authorization header for all API requests:

GET {api-url}/api/globalsettings/resort
Authorization: Bearer {access_token}

Code Examples

Python

import requests
import base64
import json
from datetime import datetime, timedelta


class FlaikConnectAuth:
    def __init__(self, client_id, client_secret, auth_url):
        self.client_id = client_id
        self.client_secret = client_secret
        self.auth_url = auth_url
        self.access_token = None
        self.token_expires = None

    def get_access_token(self, scope):
        # Check if we have a valid token
        if self.access_token and self.token_expires > datetime.now():
            return self.access_token

        # Prepare Basic Authentication
        credentials = base64.b64encode(
            f"{self.client_id}:{self.client_secret}".encode()
        ).decode()

        headers = {
            "Authorization": f"Basic {credentials}",
            "Content-Type": "application/x-www-form-urlencoded",
        }

        data = {"grant_type": "client_credentials", "scope": scope}

        # Make token request
        response = requests.post(
            f"{self.auth_url}/connect/token", headers=headers, data=data
        )

        response.raise_for_status()
        token_data = response.json()
        # print("Token Data:", json.dumps(token_data, indent=2))

        # Store token and expiration
        self.access_token = token_data["access_token"]
        self.token_expires = datetime.now() + timedelta(
            seconds=token_data["expires_in"] - 60  # Refresh 1 minute early
        )

        return self.access_token


## Example usage
if __name__ == "__main__":

    client_id = "flaik_issued_client_id"
    client_secret = "flaik_issued_client_secret"
    auth_url = "flaik_issued_auth_url"
    connect_url = "flaik_issued_connect_url"
    scope = "flaik_issued_scopes"

    auth = FlaikConnectAuth(client_id, client_secret, auth_url)
    token = auth.get_access_token(scope)
    # print("Access Token:", token)

    payload = ""
    headers = {
        "Content-Type": "application/x-www-form-urlencoded",
        "Authorization": f"Bearer {token}",
    }

    # ## Example of making an authenticated request for the Health endpoint
    health_url = f"{connect_url}/health"
    health_response = requests.request("GET", health_url, data=payload, headers=headers)
    print(health_response.text)

    # Return the Resort Info Endpoint
    resort_info_url = f"{connect_url}/api/globalsettings/resort"
    resort_info_response = requests.request(
        "GET", resort_info_url, data=payload, headers=headers
    )
    print(resort_info_response.text)

Token Management

Token Expiration

• Access tokens typically expire after 10 minutes (600 seconds)

• Always check the expires_in value in the response

• Request a new token before the current one expires

Error Handling

Sample Error Response

{
  "error": "invalid_client",
  "error_description": "Client authentication failed"
}

Testing Your Authentication

1. Health Check

Once you have a valid token, test API connectivity:

GET {api-url}/health
Authorization: Bearer {access_token}

Expected response:

{
  {"id":1,"accountName":"your_account","region":"us-west-2","environment":"staging","appName":"Connect"}
}

2. Resort Information

Verify your permissions with a simple data request:

GET {api-url}/api/globalsettings/resort
Authorization: Bearer {access_token}

This should return your resort's basic configuration data.

---

Having authentication issues? Contact [email protected] ith the specific error messages.