---
source: CrewKit documentation
url: https://crewkit.io/docs/authentication.md
title: "Authentication"
description: "Device flow, passkeys, magic links, and token management."
---


import { Callout } from 'fumadocs-ui/components/callout';

crewkit supports multiple authentication methods. The CLI uses device flow. The dashboard supports passkeys and magic links.

---

## Device flow (CLI)

The standard way to authenticate from the CLI.

### 1. Initiate

```
POST /api/v1/auth/device
```

**Response:**

```json
{
  "device_code": "abc123...",
  "user_code": "ABCD-EFGH",
  "verification_uri": "https://crewkit.io/device-verify",
  "expires_in": 600,
  "interval": 5
}
```

The CLI opens the verification URI in your browser.

### 2. Poll for token

```
POST /api/v1/auth/token
Content-Type: application/json

{
  "device_code": "abc123..."
}
```

The CLI polls this endpoint every `interval` seconds until the user approves in the browser.

**Success response:**

```json
{
  "access_token": "eyJhbGci...",
  "token_type": "Bearer",
  "expires_in": 14400,
  "refresh_token": "refresh123..."
}
```

---

## Passkeys

WebAuthn-based passwordless authentication.

### Register a passkey

```
POST /api/v1/auth/passkey/register/challenge
```

Returns a challenge for the browser to sign with the user's device.

```
POST /api/v1/auth/passkey/register
```

Completes registration with the signed challenge.

### Login with passkey

```
POST /api/v1/auth/passkey/login/challenge
POST /api/v1/auth/passkey/login
```

Same challenge-response pattern for authentication.

### Manage passkeys

```
GET /api/v1/auth/passkeys           # List registered passkeys
DELETE /api/v1/auth/passkeys/:id    # Remove a passkey
```

---

## Magic links

Passwordless login via email.

```
POST /api/v1/auth/magic_link
Content-Type: application/json

{
  "email": "user@example.com"
}
```

The user receives an email with a one-time login link.

```
POST /api/v1/auth/magic_link/verify
Content-Type: application/json

{
  "token": "<token-from-email>"
}
```

Returns access and refresh tokens on success.

---

## Token refresh

Access tokens expire after 4 hours. Use the refresh token to get new ones:

```
POST /api/v1/auth/refresh
Content-Type: application/json

{
  "refresh_token": "refresh123..."
}
```

**Response:**

```json
{
  "access_token": "eyJhbGci...",
  "refresh_token": "new_refresh123...",
  "expires_in": 14400
}
```

<Callout>
Refresh tokens are single-use. Each refresh returns a new refresh token. The old one is invalidated.
</Callout>

---

## Token revocation

Log out by revoking your tokens:

```
POST /api/v1/auth/revoke
Authorization: Bearer <access_token>
```

Or use the alias:

```
DELETE /api/v1/auth/logout
Authorization: Bearer <access_token>
```

---

## Current user

```
GET /api/v1/auth/me
Authorization: Bearer <access_token>
```

Returns the authenticated user's profile.

```
PATCH /api/v1/auth/me
```

Update your profile.

```
GET /api/v1/auth/organizations
```

List organizations the authenticated user belongs to.

---

## Next steps

- [API overview](/docs/api-overview)
- [Sessions API](/docs/api-sessions)