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

# mFoundry REST API Authentication: Bearer Token Setup

> Every mFoundry API request requires a Bearer token in the Authorization header. Learn how to include your key and handle 401 and 403 responses.

Every request you make to the mFoundry REST API must include a valid API key as a Bearer token in the `Authorization` header. Without it, the API immediately rejects the request with a `401 Unauthorized` response. Keep your key secure — treat it with the same care as a password.

## Authorization Header

Include the following header with every API request, replacing `YOUR_API_KEY` with your actual key:

```
Authorization: Bearer YOUR_API_KEY
```

The examples below show how to set this header in a shell command and in client-side JavaScript:

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.mfoundry.io/v1/projects \
    --header "Authorization: Bearer YOUR_API_KEY" \
    --header "Content-Type: application/json"
  ```

  ```javascript JavaScript (fetch) theme={null}
  const response = await fetch("https://api.mfoundry.io/v1/projects", {
    method: "GET",
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
  });

  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

## Obtaining an API Key

You generate API keys from your mFoundry account settings. See the [API Keys guide](/getting-started/authentication) for a step-by-step walkthrough of creating a key, setting its scopes, and rotating it when needed. Each key is displayed only once at creation time — copy it immediately and store it in a secrets manager or environment variable.

## Key Scopes

Not all API keys have the same level of access. When you create a key at **Settings > API Keys**, you choose its scope:

* **Read-only** — the key can call `GET` endpoints but cannot create, update, or delete resources.
* **Full access** — the key can call all endpoints your account role permits.
* **Resource-scoped** — some keys can be restricted to specific resources (for example, projects only), preventing accidental access to user or webhook endpoints.

Always issue the least-privileged key your integration actually needs.

## Error Responses

When authentication fails, the API returns one of the following errors:

| Status | Code           | Meaning                                                                            |
| ------ | -------------- | ---------------------------------------------------------------------------------- |
| `401`  | `unauthorized` | The `Authorization` header is missing, malformed, or contains an invalid API key   |
| `403`  | `forbidden`    | The API key is valid but does not have permission to access the requested resource |

A `401` means you need to check that your key is correct and properly formatted. A `403` means the key is recognized but scoped too narrowly — you need a key with broader permissions or the appropriate resource scope.

<Warning>
  Never embed your API key directly in client-side code, browser JavaScript, or version control. If a key is ever exposed, revoke it immediately from **Settings > API Keys** and issue a new one. Use environment variables or a dedicated secrets manager to inject keys at runtime.
</Warning>