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

# Authentication

> How to authenticate with the Cryptorobot.ai API

## Overview

Cryptorobot.ai supports multiple authentication strategies:

| Strategy                     | Use Case                | Method                          |
| ---------------------------- | ----------------------- | ------------------------------- |
| **Local (Email + Password)** | User login from apps    | `POST /authentication`          |
| **Google OAuth**             | Social login            | OAuth2 redirect flow            |
| **JWT Bearer Token**         | Authenticated API calls | `Authorization: Bearer <token>` |
| **API Key**                  | Server-to-server / bots | `Authorization: ApiKey <key>`   |

## Login (Local Strategy)

Exchange email and password for a JWT access token:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.cryptorobot.ai/authentication \
    -H "Content-Type: application/json" \
    -d '{
      "strategy": "local",
      "email": "user@example.com",
      "password": "your-password"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.cryptorobot.ai/authentication', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      strategy: 'local',
      email: 'user@example.com',
      password: 'your-password'
    })
  });

  const { accessToken, user } = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post('https://api.cryptorobot.ai/authentication', json={
      'strategy': 'local',
      'email': 'user@example.com',
      'password': 'your-password'
  })

  data = response.json()
  token = data['accessToken']
  user = data['user']
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "authentication": {
    "strategy": "local",
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  },
  "user": {
    "_id": "507f1f77bcf86cd799439011",
    "email": "user@example.com",
    "name": "John Doe",
    "plan": "pro",
    "verified": true
  }
}
```

## Using the Token

Include the JWT token in the `Authorization` header for all authenticated requests:

```bash theme={null}
curl https://api.cryptorobot.ai/strategies \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```

<Warning>
  Tokens expire after a configured TTL (default: 7 days). When a token expires, you'll receive a `401 Not Authenticated` error. Re-authenticate to get a fresh token.
</Warning>

## Token Refresh

Tokens can be refreshed by authenticating with the existing (still valid) token:

```bash theme={null}
curl -X POST https://api.cryptorobot.ai/authentication \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJ..." \
  -d '{"strategy": "jwt", "accessToken": "eyJ..."}'
```

## Google OAuth

For web applications, redirect users to the Google OAuth flow:

```
GET https://api.cryptorobot.ai/oauth/google
```

After successful authentication, the user is redirected to your callback URL with the JWT token.

## Logout

Invalidate the current session:

```bash theme={null}
curl -X DELETE https://api.cryptorobot.ai/authentication \
  -H "Authorization: Bearer eyJ..."
```

This revokes the session server-side. The JWT will be rejected on subsequent requests.

## Session Management

List active sessions for the current user:

```bash theme={null}
curl https://api.cryptorobot.ai/users/sessions \
  -H "Authorization: Bearer eyJ..."
```

```json theme={null}
{
  "total": 3,
  "data": [
    {
      "_id": "session-id-1",
      "userAgent": "Mozilla/5.0...",
      "ip": "192.168.1.1",
      "createdAt": "2024-01-15T10:00:00Z",
      "lastActive": "2024-01-15T14:30:00Z"
    }
  ]
}
```

## Security Best Practices

<AccordionGroup>
  <Accordion title="Store tokens securely">
    Never expose JWT tokens in client-side JavaScript, URLs, or logs. Use `httpOnly` cookies or secure storage mechanisms.
  </Accordion>

  <Accordion title="Use API keys for bots">
    For automated trading bots and server-to-server communication, use [API keys](/guides/api-keys) instead of user credentials.
  </Accordion>

  <Accordion title="Rotate credentials regularly">
    Periodically rotate API keys and re-authenticate to minimize exposure from leaked credentials.
  </Accordion>

  <Accordion title="Use HTTPS only">
    All API requests must use HTTPS. HTTP requests are rejected.
  </Accordion>
</AccordionGroup>

## Email Verification

New accounts must verify their email before full access is granted:

```bash theme={null}
# Resend verification email
curl -X POST https://api.cryptorobot.ai/auth-management \
  -H "Content-Type: application/json" \
  -d '{"action": "resendVerifySignup", "value": {"email": "user@example.com"}}'
```

## Password Reset

```bash theme={null}
# Request password reset
curl -X POST https://api.cryptorobot.ai/auth-management \
  -H "Content-Type: application/json" \
  -d '{"action": "sendResetPwd", "value": {"email": "user@example.com"}}'

# Complete password reset (with token from email)
curl -X POST https://api.cryptorobot.ai/auth-management \
  -H "Content-Type: application/json" \
  -d '{"action": "resetPwdLong", "value": {"token": "reset-token-from-email", "password": "new-password"}}'
```