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

# Authentication

> Learn how to authenticate your requests to the PlanD API using Bearer tokens or API keys

The PlanD API uses Bearer token authentication and API key authentication to secure your requests. You must include authentication credentials in your requests to access the API.

## Authentication Methods

<Tabs>
  <Tab title="Bearer Token">
    Include your Bearer token in the Authorization header:

    ```bash theme={null}
    Authorization: Bearer YOUR_JWT_TOKEN
    ```

    <RequestExample>
      ```bash cURL theme={null}
      curl -X GET "https://cloud-api.pland.app/v2/users" \
        -H "Authorization: Bearer YOUR_JWT_TOKEN" \
        -H "Content-Type: application/json"
      ```
    </RequestExample>

    <Note>
      The Bearer token uses JWT (JSON Web Token) format as specified in the API security schemes.
    </Note>
  </Tab>

  <Tab title="API Key">
    Include your API key in the x-API-Key header:

    ```bash theme={null}
    x-API-Key: YOUR_API_KEY
    ```

    <RequestExample>
      ```bash cURL theme={null}
      curl -X GET "https://cloud-api.pland.app/v2/users" \
        -H "x-API-Key: YOUR_API_KEY" \
        -H "Content-Type: application/json"
      ```
    </RequestExample>
  </Tab>
</Tabs>

## API Servers

The PlanD API is available on multiple servers:

<CardGroup cols={3}>
  <Card title="Production" icon="cloud">
    **[https://cloud-api.pland.app/v2](https://cloud-api.pland.app/v2)**

    Production environment for live applications
  </Card>

  <Card title="Sandbox" icon="flask">
    **[https://beta-api.pland.app/v2](https://beta-api.pland.app/v2)**

    Testing environment for development
  </Card>

  <Card title="Local Development" icon="laptop">
    **[http://localhost:3000/v2](http://localhost:3000/v2)**

    Local development server
  </Card>
</CardGroup>

## Getting API Keys

You can manage your API keys through the API itself:

<Steps>
  <Step title="List existing API keys">
    Use the `GET /apiKeys` endpoint to view your current API keys

    ```bash theme={null}
    GET /apiKeys?limit=10&offset=0
    ```
  </Step>

  <Step title="Create a new API key">
    Use the `POST /apiKeys` endpoint to generate a new API key

    <Warning>
      The API key is returned in clear text only once during creation
    </Warning>
  </Step>

  <Step title="Store securely">
    Store your API key in environment variables or secure configuration

    ```bash theme={null}
    export PLAND_API_KEY="your_api_key_here"
    ```
  </Step>
</Steps>

## User Authentication

For user login and authentication management:

<Tabs>
  <Tab title="User Login">
    Authenticate users with username and password:

    ```bash theme={null}
    POST /auth/login
    ```

    <RequestExample>
      ```bash cURL theme={null}
      curl -X POST "https://cloud-api.pland.app/v2/auth/login" \
        -H "Content-Type: application/json" \
        -d '{
          "username": "user@example.com",
          "password": "SecurePassword123",
          "type": "dashboard"
        }'
      ```
    </RequestExample>
  </Tab>

  <Tab title="SMS Authentication">
    Request SMS verification code:

    ```bash theme={null}
    POST /auth/requestAuthCode
    ```

    Then authenticate with the code:

    ```bash theme={null}
    POST /auth/authUsingSMS
    ```
  </Tab>

  <Tab title="Change Password">
    Change user password:

    ```bash theme={null}
    POST /account/change-password
    ```

    Requires current password verification.
  </Tab>
</Tabs>

## Testing Authentication

Verify your authentication is working correctly:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://cloud-api.pland.app/v2/users" \
    -H "Authorization: Bearer YOUR_JWT_TOKEN"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://cloud-api.pland.app/v2/users', {
    headers: {
      'Authorization': `Bearer ${process.env.PLAND_JWT_TOKEN}`,
      'Content-Type': 'application/json'
    }
  });

  if (response.ok) {
    console.log('Authentication successful');
  } else {
    console.error('Authentication failed');
  }
  ```

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

  headers = {
      'Authorization': f'Bearer {os.getenv("PLAND_JWT_TOKEN")}',
      'Content-Type': 'application/json'
  }

  response = requests.get('https://cloud-api.pland.app/v2/users', headers=headers)

  if response.status_code == 200:
      print('Authentication successful')
  else:
      print('Authentication failed')
  ```
</CodeGroup>

## Common Authentication Errors

<AccordionGroup>
  <Accordion title="401 Unauthorized">
    **Common causes:**

    * Invalid or expired JWT token
    * Missing Authorization header
    * Invalid API key

    **Solutions:**

    * Verify your token/key is correct
    * Check the header format matches the specification
    * Ensure the token hasn't expired
  </Accordion>

  <Accordion title="403 Forbidden">
    **Common causes:**

    * Valid authentication but insufficient permissions
    * API key doesn't have required access level

    **Solutions:**

    * Check your account permissions
    * Verify the API key has the necessary scope
    * Contact your administrator for access
  </Accordion>
</AccordionGroup>

## Security Best Practices

<CardGroup cols={2}>
  <Card title="Environment Variables" icon="shield">
    Store credentials in environment variables, never in code

    ```bash theme={null}
    export PLAND_JWT_TOKEN="your_jwt_token_here"
    export PLAND_API_KEY="your_api_key_here"
    ```
  </Card>

  <Card title="Token Management" icon="key">
    Regularly rotate your API keys and monitor their usage

    Use the API key management endpoints to track active keys
  </Card>
</CardGroup>