> ## Documentation Index
> Fetch the complete documentation index at: https://developers.techwolf.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

The Skill Engine API uses OAuth 2.0 for authentication with support for two methods:
**Client Credentials Flow** and **Private Key JWT Authentication**.

## Getting Started

Contact your TechWolf representative to obtain your credentials:

* `client_id` - Your unique client identifier
* `audience` - The API audience
* `tenant` - Your organization's tenant identifier
* Method-specific credentials (client secret or private key)

**Token Endpoints:**

* **EU tenants**: `https://techwolf.eu.auth0.com/oauth/token`
* **US tenants**: `https://techwolf-us.us.auth0.com/oauth/token`

**Audience:**

* **EU tenants**: `eu3.techwolf.ai`
* **US tenants**: `us3.techwolf.ai`

<Warning>
  **Cache your tokens!** Tokens expire and requesting new ones adds latency. Always reuse tokens until they expire.
</Warning>

### Client Credentials Flow

Simple server-to-server authentication using a shared secret.

Contact your TechWolf representative to obtain your credentials.

**What TechWolf provides to you:**

* The `client_id` and `client_secret`

#### Step 1: Request a token

**Basic Request:**

```bash theme={null}
curl -X POST 'https://techwolf.eu.auth0.com/oauth/token' \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": "<your_client_id>",
    "client_secret": "<your_client_secret>",
    "audience": "eu3.techwolf.ai",
    "grant_type": "client_credentials",
    "tenant": "<your_tenant>"
  }'
```

**With Scopes:**

```bash theme={null}
curl -X POST 'https://techwolf.eu.auth0.com/oauth/token' \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": "<your_client_id>",
    "client_secret": "<your_client_secret>",
    "audience": "eu3.techwolf.ai",
    "grant_type": "client_credentials",
    "tenant": "<your_tenant>",
    "scopes": ["read", "write"]
  }'
```

### Private Key JWT Authentication

Enhanced security using asymmetric cryptography - no shared secrets to store.

**What you need to provide to TechWolf:**

* The public key associated with your private key

**What TechWolf provides to you:**

* The `client_id`

#### Step 1: Create JWT Assertion

Sign a JWT with your private key containing these claims:

```json theme={null}
{
  "iss": "your_client_id",
  "sub": "your_client_id", 
  "aud": "https://techwolf.eu.auth0.com/oauth/token",
  "exp": 1640995200,
  "iat": 1640994900,
  "jti": "unique-jwt-id-12345"
}
```

**Requirements:**

* Sign with RS256 algorithm
* Set `exp` 5-10 minutes in the future
* Use unique `jti` for each request
* Include current timestamp in `iat`

#### Step 2: Exchange JWT for Token

**Basic Request:**

```bash theme={null}
curl -X POST 'https://techwolf.eu.auth0.com/oauth/token' \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "client_credentials",
    "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
    "client_assertion": "<your_jwt_assertion>",
    "audience": "eu3.techwolf.ai",
    "tenant": "<your_tenant>"
  }'
```

The `assertion` field is the JWT you just created and signed with your private key.

**With Scopes:**

```bash theme={null}
curl -X POST 'https://techwolf.eu.auth0.com/oauth/token' \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "client_credentials",
    "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
    "client_assertion": "<your_jwt_assertion>",
    "audience": "eu3.techwolf.ai", 
    "tenant": "<your_tenant>",
    "scopes": ["read", "write"]
  }'
```

## Token Response

Both methods return a JSON object with the following fields:

```json theme={null}
{
  "access_token": "eyJhbGciOiJSUzI0I0seiEw...",
  "expires_in": 10800,
  "scope": "read write",
  "token_type": "Bearer"
}
```

## Scopes

| Scope          | Access                                        |
| -------------- | --------------------------------------------- |
| `read`         | Read API resources                            |
| `write`        | Write API resources                           |
| `read_reports` | Read access to reports (only aggregated info) |

*Default: All available scopes for your credentials*

## Using Your Token

Add to the `Authorization` header of all API calls:

```bash theme={null}
curl -X GET '[server-url]/your-endpoint' \
  -H 'Authorization: Bearer <access_token_returned_in_response>'
```

**Test your token:**

```bash theme={null}
curl -X GET '[server-url]/version' \
  -H 'Authorization: Bearer <access_token_returned_in_response>'
```

## Additional Resources

* [OAuth 2.0 Client Credentials](https://auth0.com/docs/api/authentication#client-credentials-flow)
* [JWT Bearer Token Spec](https://tools.ietf.org/html/rfc7523)