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

# Authentication

> Learn how to authenticate with the North API

# Authentication

The North API uses API keys for authentication. Each key is scoped to your team and can have specific permissions.

## Getting your API key

1. Log into your [North Dashboard](https://northreports.com/dashboard)
2. Navigate to **Settings > Integrations**
3. Click **Create API Key**
4. Give it a descriptive name (e.g., "Zapier Integration")
5. Optionally add a description and expiration date
6. Copy your key immediately - **you won't see it again!**

API keys have full access to your team's data, making it simple to integrate with any service.

<Warning>
  Keep your API key secure! Treat it like a password. Never commit it to version control or share it publicly.
</Warning>

## Using your API key

Include your API key in the `Authorization` header of every request:

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

### Example request

```bash theme={null}
curl -X GET \
  "https://api.northreports.com/v1/users/me" \
  -H "Authorization: Bearer north_sk_live_YOUR_KEY_HERE"
```

## API Key format

North API keys follow this format:

```
north_sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

* `north_sk_` - Identifies it as a North secret key
* `live_` - Indicates production environment
* `xxx...` - 32 character random string

## Permissions

API keys have full access to all your team's resources:

| Resource         | Capabilities                                      |
| ---------------- | ------------------------------------------------- |
| **Reports**      | Create, read, update, delete, and publish reports |
| **Comps**        | Manage comparable properties                      |
| **Showings**     | Track showings and open houses                    |
| **Social Media** | Import engagement data                            |
| **AI Insights**  | Generate summaries and insights                   |
| **Team Info**    | View team details                                 |

<Tip>
  Each API key is scoped to your team only. You cannot access data from other teams.
</Tip>

## Common authentication errors

### 401 Unauthorized

```json theme={null}
{
  "error": {
    "message": "Invalid API key",
    "status": 401
  }
}
```

**Causes:**

* Missing `Authorization` header
* Incorrect key format
* Key doesn't exist or was revoked

### 403 Forbidden

```json theme={null}
{
  "error": {
    "message": "Permission denied: reports:create",
    "status": 403
  }
}
```

**Cause:** Your API key doesn't have the required permission for this operation.

## Key management best practices

<AccordionGroup>
  <Accordion title="Rotate keys regularly">
    Create new keys periodically and revoke old ones. This limits exposure if a key is compromised.
  </Accordion>

  <Accordion title="Use descriptive names">
    Name keys based on their purpose: "Zapier Automation", "CRM Sync", "Marketing Dashboard"
  </Accordion>

  <Accordion title="Set expiration dates">
    For temporary integrations, set an expiration date on the key.
  </Accordion>

  <Accordion title="Monitor usage">
    Check the "Last Used" timestamp in your dashboard to identify unused keys.
  </Accordion>

  <Accordion title="One key per integration">
    Create separate keys for each integration. This makes it easy to revoke access without affecting other systems.
  </Accordion>
</AccordionGroup>

## Revoking a key

If you suspect a key has been compromised:

1. Go to **Settings > Integrations**
2. Find the compromised key
3. Click **Revoke**
4. The key is immediately invalidated

Any requests using that key will receive a 401 error.

## Testing your key

Use the "Get Current User" endpoint to verify your key is working:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET \
    "https://api.northreports.com/v1/users/me" \
    -H "Authorization: Bearer north_sk_live_YOUR_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.northreports.com/v1/users/me',
    {
      headers: {
        'Authorization': 'Bearer north_sk_live_YOUR_KEY'
      }
    }
  );

  const data = await response.json();
  console.log(data);
  ```

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

  response = requests.get(
      'https://api.northreports.com/v1/users/me',
      headers={
          'Authorization': 'Bearer north_sk_live_YOUR_KEY'
      }
  )

  print(response.json())
  ```
</CodeGroup>

A successful response means your key is valid and you're ready to start building!