> For the complete documentation index, see [llms.txt](https://knowledgebase.flaik.com/flaik-knowledge-base/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://knowledgebase.flaik.com/flaik-knowledge-base/for-it-specialists/3.-flaik-connect-api/overview/authentication.md).

# Authentication

### Overview

flaik Connect uses **OAuth 2.0 client-credentials** for authentication. Every API call must include a bearer token, which you obtain by exchanging the `client_id` and `client_secret` issued to your integration.

Tokens are JWTs signed by flaik's identity server and are valid for **1 hour**. There is no refresh token — fetch a new one when the old one expires.

### Getting Credentials

Resort integrations are credentialed by flaik. To request a `client_id` and `client_secret`, contact <resortsupport@flaik.com>. You will be issued one credential pair per resort, scoped to the read/write access your integration needs.

### Token Endpoint

```http
POST https://auth-usw2.flaik.com/connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id={your_client_id}
&client_secret={your_client_secret}
&scope=flaik.connect.api.read
```

Replace the `scope` value with the scope(s) your integration needs (see Scopes below). Multiple scopes are space-separated.

#### Example — fetch a token

```bash
curl -X POST https://auth-usw2.flaik.com/connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=your-client-id" \
  -d "client_secret=your-client-secret" \
  -d "scope=flaik.connect.api.read"
```

#### Successful Response

```json
{
  "access_token": "eyJhbGciOiJSUzI1NiIs…",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "flaik.connect.api.read"
}
```

| Field          | Type    | Description                                               |
| -------------- | ------- | --------------------------------------------------------- |
| `access_token` | string  | JWT to send with every API call                           |
| `expires_in`   | integer | Token lifetime in seconds (typically `3600` = 1 hour)     |
| `token_type`   | string  | Always `"Bearer"`                                         |
| `scope`        | string  | Space-separated list of scopes the token actually carries |

### Calling the API

Pass the token as a `Bearer` token in the `Authorization` header on every request:

```http
GET https://api.flaik.com/api/globalsettings/seasons
Authorization: Bearer eyJhbGciOiJSUzI1NiIs…
```

> **Note:** the API base URL (`https://api.flaik.com` shown above) is environment-specific — Flaik will provide the correct URL for your integration. The token endpoint URL is the same for all resort integrations.

### Scopes

Request the scope(s) your integration needs when fetching a token. Multiple scopes are space-separated.

| Scope                     | Required for                                                                                                    |
| ------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `flaik.connect.api.read`  | All read endpoints (Schedule, Class Management, Global Settings, POS Integration, Timekeeping, Search Employee) |
| `flaik.connect.api.write` | Write endpoints (Upsert Employee, Upsert Status)                                                                |
| `flaik.connect.api.admin` | Reserved for future administrative endpoints                                                                    |

### Token Caching

Always cache and reuse access tokens — fetching a new one on every API call wastes both ends. Recommended pattern:

1. Fetch a token on first use.
2. Cache it in memory along with its expiry time.
3. Reuse it until \~5 minutes before expiry, then fetch a new one.
4. On a `401` response from the API (indicating the token is invalid or has rotated), discard the cached token and fetch a new one before retrying once.

A simple "fetch on demand with short safety margin" cache works well for most integrations.

### Errors

#### Token endpoint errors

The IdentityServer token endpoint returns standard OAuth 2.0 error responses (RFC 6749). The most common:

| `error`               | What it means                                                                         |
| --------------------- | ------------------------------------------------------------------------------------- |
| `invalid_client`      | `client_id` or `client_secret` is wrong, or the client is disabled                    |
| `invalid_scope`       | One of the scopes you requested isn't allowed for this client                         |
| `unauthorized_client` | The client exists but isn't allowed to use the `client_credentials` grant type        |
| `invalid_request`     | A required field (`grant_type`, `client_id`, `client_secret`) is missing or malformed |

Example response:

```json
{
  "error": "invalid_client",
  "error_description": "client credentials are invalid"
}
```

#### API errors related to authentication

When calling flaik Connect endpoints with a missing or invalid token:

| HTTP Status | Cause                                                                                                   |
| ----------- | ------------------------------------------------------------------------------------------------------- |
| `401`       | Token missing, expired, or signature invalid. Fetch a new one and retry.                                |
| `403`       | Token is valid but doesn't include the scope this endpoint requires. Re-credential with broader scopes. |

See the [Error Handling](https://knowledgebase.flaik.com/flaik-knowledge-base/for-it-specialists/3.-flaik-connect-api/overview/error-handling) page for full status-code semantics.

### Tenant Binding

Every `client_id` is permanently bound to a single resort tenant — flaik resolves the tenant from your credentials, not from a header or query parameter. As a result:

* You don't pass a tenant identifier on any request.
* A token issued for Resort A cannot read or write data for Resort B.
* If your integration covers multiple resorts, you'll receive one credential pair per resort and should keep token caches per-resort.

Need help with credentials or scopes? Contact <resortsupport@flaik.com>.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://knowledgebase.flaik.com/flaik-knowledge-base/for-it-specialists/3.-flaik-connect-api/overview/authentication.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.