# Authentication

Most REST API requests require an [`Authorization` header][auth header] to securely
access and modify server resources. The Metafold REST API uses [JSON Web Tokens
(JWT)][jwt] for secure authentication. At the moment the only method to retrieve a JWT
is through a **client credentials authorization flow**, which is often best handled
using a third-party library. This document describes a few convenient options, though it
is far from exhaustive!

## Creating a client

Client credentials (ID and secret pair) are required to authenticate with the Metafold
API. You may create a client through the [Metafold account page][metafold clients].

![Create client page on Metafold account dashboard](https://storage.googleapis.com/metafold_static-1/docs/metafold_clients.png)

> info
> The client secret **must** be kept secure.
>
> In the event the client ID and secret are compromised, attackers may gain **full
> access** to the user’s private resources. The compromised client may be deleted from
> the [account page][metafold clients] to invalidate existing access tokens and prevent
> further client credentials exchanges.
>
> While access tokens expire within **24 hours**, they provide direct access to user
> resources and should also be kept secret.

## Exchanging an access token (HTTP POST)

The client ID/secret pair must be exchanged for an access token that may be used to
authenticate with the Metafold API. Exchanging your client credentials can be done with
a HTTP `POST` request to our authentication service:

```
POST https://metafold3d.us.auth0.com/oauth/token
```

With the following parameters in the request body:

| Parameter | Description |
| --- | --- |
| `grant_type` | Must be `client_credentials`. |
| `audience` | Must be `https://api.metafold3d.com`. |
| `client_id` | Your client ID. |
| `client_secret` | Your client secret. |

The response is encoded as `application/json` and includes the following fields:

| Field | Description |
| --- | --- |
| `access_token` | [JWT][] access token that may be used to authenticate with the Metafold API. |
| `expires_in` | The returned access token expires in this many seconds. |

Note that new access tokens expire within **24 hours** and must be refreshed to renew
access to our API.

Access tokens should be included in the request header in the following form:

```bash
Authorization: Bearer $access_token
```

## Exchanging an access token (Auth0 SDK)

You may alternatively find it easier to authenticate using one of [Auth0’s many SDK
libraries][auth0 libs]. The example below uses the [Auth0 Node.js SDK][].

```js
import { AuthenticationClient } from "auth0";

const API_BASE_URL = "htttps://api.metafold3d.com/";

const auth0 = new AuthenticationClient({
  domain: "metafold3d.us.auth0.com",
  clientId: "<client_id>",
  clientSecret: "<client_secret>",
});
const { data: { access_token: accessToken } } = await auth0.oauth.clientCredentialsGrant({ audience: API_BASE_URL });
console.debug(accessToken); // e.g. "eyJhbGciOi..."

const url = new URL("/user/usage", API_BASE_URL);
const res = await fetch(url, {
  headers: {
    Authorization: `Bearer ${accessToken}`,
    Accept: "application/json",
  },
});
console.debug(await res.json()); // { projects: 32, assets: 64, ... }
```

Auth0’s SDKs often provide additional handling for refreshing tokens, etc.

## Exchanging an access token (Metafold Python SDK)

Perhaps the most convenient option is to rely on the Metafold SDK to automatically
handle authentication. The example below uses the [Metafold Python SDK][] (this feature
is not yet supported in the [Metafold Node.js SDK][]).

```python
from metafold import MetafoldClient

client = MetafoldClient(
		client_id="<client_id>",
		client_secret="<client_secret>",
)
projects = client.projects.list()
print(projects)  # [Project(id='123', ...)]
```

Tokens are automatically refreshed when needed.

[Auth0 Node.js SDK]: https://github.com/auth0/node-auth0
[Metafold Node.js SDK]: https://github.com/Metafold3d/metafold-node
[Metafold Python SDK]: https://github.com/Metafold3d/metafold-python
[auth header]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Authorization
[auth0 libs]: https://auth0.com/docs/libraries
[jwt]: https://datatracker.ietf.org/doc/html/rfc7519
[metafold clients]: https://account.metafold3d.com/settings/clients