# Authentication

## Introduction

The Core API offers two authentication mechanisms: [API keys](#api-keys) and [OAuth 2](#oauth-2-client-credentials). API key authentication is the preferred method as it doesn't require any extra authentication calls. 

## API Keys

These provide great security whilst minimising the authentication complexity. The API key should be passed in the `Authorization` header in every request. Follow [this guide](https://app.gitbook.com/s/LYNcUBVQwSkOMG6KjZfz/developer-hub/patchworks-core-api/core-api-authentication/api-keys#generating-api-keys) to generate an API key. 

We recommend using a different API key for each system connected to Patchworks. You can create as many as you need. 

API keys do not expire, unlike the token gained via OAuth 2. Whichever method you use, the same usage limits apply. If you no longer use a key, please revoke it. Requests using invalid API keys will return a 401 response.

{% hint style="info" %}
Authenticating with an API key provides manager-level access via the API. Some API requests require `administrator` access - if you are an `administrator`, authenticating with a [bearer token (using OAuth 2 client credentials)](#oauth-2-client-credentials) provides a higher level of access.
{% endhint %}

## OAuth 2 (client credentials)

Your account username and password can be used to gain a token to be put in the `Authorization` header to authenticate requests. This follows a simplified client credentials flow. The first request should be:

{% code lineNumbers="true" %}

```http
POST /fabric/api/login HTTP/1.1
Host: app.wearepatchworks.com
Content-Type: application/json
Accept: application/json
{
    "username": "me@patchworks.com",
    "password": "a1b2c3d4e5f6"
}
```

{% endcode %}

A successful response will return the following content with a `200` status code:

{% code lineNumbers="true" %}

```json
{
"message": "You have successfully logged in.",
"token": "eyJ0eXAiOiJKV......",
"expires_in": 86400
}
```

{% endcode %}

The content in the `token` field should be used as your access token inside the `Authorization` header (along with the term `Bearer` to illustrate the token type):

`Authorization: Bearer eyJ0eXAiOiJKV......`

Authentication tokens expire after the length of time indicated in the response (in seconds). An invalid or expired token results in a `401` status code response. You should reauthenticate to get a new token.

## Authorisation

[API Keys](#api-keys) and [OAuth](#oauth-2-client-credentials) tokens behave slightly differently when it comes to authorisation. 

A request authenticated with an OAuth token inherits the permissions associated with the user credentials used to create the token. Keep this in mind when using your own credentials or those of another high-level user.

API keys work by creating a new user on your company account with [manager-level access](https://app.gitbook.com/s/LYNcUBVQwSkOMG6KjZfz/users-roles-and-permissions). A new user is created for each API key created. The user will have the role `api-user`. This access level ensures the API key can be used for almost all needs except those that only an account `administrator` needs (such as blueprint management).