# Authentication

> Authenticate your users with Cephable using the OAuth 2.0 Authorization Code flow.

Source: https://developers.cephable.com/docs/api-reference/authentication

---
## Authentication model

Cephable uses **OAuth 2.0 Authorization Code** flow to authenticate users. Your application:

1. Redirects the user to the Cephable login page
2. Receives an authorization code at your redirect URI
3. Exchanges the code for an access token and refresh token
4. Uses the access token to call the Cephable API on behalf of the user

> **Security:** Never expose your `CLIENT_SECRET` in client-side code or public repositories.

## Getting credentials

1. Sign in to the [Cephable Portal](https://portal.cephable.com)
2. Create or open a project
3. Copy your **Client ID**, **Client Secret**, and **Device Type ID**

## Step 1 — Redirect user to Cephable login

Construct the authorization URL and redirect the user:

```
https://services.cephable.com/signin?client_id={CLIENT_ID}&redirect_uri={REDIRECT_URI}&response_type=code
```

**Parameters:**

| Parameter | Description |
|-----------|-------------|
| `client_id` | Your application's OAuth client ID |
| `redirect_uri` | The URL Cephable will redirect back to with the code |
| `response_type` | Always `code` |

### JavaScript example

```javascript
const CLIENT_ID = "YOUR_CLIENT_ID";
const redirectUri = window.location.origin + window.location.pathname;
const authUrl = `https://services.cephable.com/signin?redirect_uri=${encodeURIComponent(redirectUri)}&client_id=${CLIENT_ID}`;
window.location.href = authUrl;
```

### C# / Unity example

```csharp
string redirectUri = "http://localhost:51772/";
string authUrl = $"https://services.cephable.com/signin?client_id={CLIENT_ID}&redirect_uri={redirectUri}&response_type=code";
Application.OpenURL(authUrl);
```

## Step 2 — Exchange the authorization code for a token

After the user logs in, Cephable redirects to your `redirect_uri` with a `code` query parameter. Exchange it for tokens:

```http
POST https://services.cephable.com/signin/token?grant_type=code&code={code}&client_id={CLIENT_ID}&redirect_uri={REDIRECT_URI}
```

**Response:**

```json
{
  "access_token": "eyJ...",
  "refresh_token": "...",
  "access_token_expiration": "...",
  "refresh_token_expiration": "..."
}
```

### JavaScript example

```javascript
const response = await axios.post(
  `https://services.cephable.com/signin/token?client_id=${clientId}&code=${encodeURIComponent(code)}&redirect_uri=${encodeURIComponent(redirectUri)}&grant_type=code`
);
const accessToken = response.data.access_token;
```

### C# / Unity example

```csharp
UnityWebRequest www = UnityWebRequest.Post(
  $"https://services.cephable.com/signin/token?grant_type=code&code={authCode}&client_id={CLIENT_ID}&redirect_uri={REDIRECT_URI}",
  string.Empty
);
yield return www.SendWebRequest();
var tokenResponse = TokenResponse.CreateFromJSON(www.downloadHandler.text);
PlayerPrefs.SetString("accessToken", tokenResponse.access_token);
```

## Step 3 — Refresh tokens

Use the refresh token to get a new access token without re-authenticating the user:

```http
POST https://services.cephable.com/signin/token?grant_type=refresh_token&client_secret={CLIENT_SECRET}&refresh_token={REFRESH_TOKEN}&client_id={CLIENT_ID}&redirect_uri={REDIRECT_URI}
```

### C# / Unity example

```csharp
string refreshToken = PlayerPrefs.GetString("refreshToken");
UnityWebRequest www = UnityWebRequest.Post(
  $"https://services.cephable.com/signin/token?grant_type=refresh_token&client_secret={CLIENT_SECRET}&refresh_token={refreshToken}&client_id={CLIENT_ID}&redirect_uri={REDIRECT_URI}",
  string.Empty
);
yield return www.SendWebRequest();
var tokenResponse = TokenResponse.CreateFromJSON(www.downloadHandler.text);
```

## Using the access token

Add the token to the `Authorization` header of every API request:

```http
Authorization: Bearer {access_token}
```

## Token response model

```json
{
  "access_token": "string",
  "refresh_token": "string",
  "access_token_expiration": "string",
  "refresh_token_expiration": "string"
}
```

## Next steps

- [API Reference Overview](/docs/api-reference/overview) — Device API and hub
- [Swagger UI](https://services.cephable.com/swagger) — Interactive API explorer
- [Virtual Controller Integration](/docs/game-integrations/virtual-controller)
- [Unity Integration](/docs/game-integrations/unity)