Authentication

Introduction

The Core API offers two authentication mechanisms: API keys and OAuth 2. 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 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.

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) provides a higher level of access.

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:

POST https://svc-fabric.wearepatchworks.com/api/v1/login HTTP/1.1
Host: app.wearepatchworks.com
Content-Type: application/json
Accept: application/json
{
    "username": "[email protected]",
    "password": "a1b2c3d4e5f6"
}

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

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

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 and OAuth 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. 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).