---
title: Authentication
slug: api/authentication
description: Learn how to authenticate your application using Formedix REST APIs with OAuth2. This document provides comprehensive information on the three authentication methods available and the authentication request endpoint. It also explains how to handle differe
createdAt: 2023-07-21T11:41:03.318Z
---

Formedix REST APIs are authenticated using an OAuth2 ‘client ID’ and ‘secret’.
The clientID/secret combination uniquely identifies the company and context of the API call.

To use our APIs, a unique `client_id` and `client_secret` is provided by Formedix. Please contact us if you require new credentials.

### Authenticate a new OAuth2 Session

This request authenticates your OAuth2 client credentials and prepares an authentication token for use in API requests.

:::BlockQuote
Authentication request endpoint:
:::

:::CodeblockTabs
Endpoint

```none
POST   {baseUrl}/fws/api/oauth/token
```
:::

You can supply your company's `client_id` and `client_secret` credentials to authenticate an OAuth2  session using one of the following three methods:

1. Concatenating the `client_id` and `client_secret` by a colon, and then passing the Base64 encoded result as the HTTP Basic credentials in the authorization header. This method is recommended.
2. Providing the credentials as `client_id` and `client_secret` body parameters in a `application/x-www-form-urlencoded` request.\*
3. Providing the credentials as `client_id` and `client_secret` properties in a JSON body for a `application/json` request (see example request aside).\*

:::BlockQuote
Example authentication request as `application/json` body:
:::

:::CodeblockTabs
Request

```JSON
 {
  "grant_type": "client_credentials",
  "client_id": "<yourClientId>",
  "client_secret": "<yourClientSecret>"
}
```
:::

\*The fallback method body content is ignored when the authorization header is present, or if alternative content-types are specified.

:::BlockQuote
The example request above returns the following response:
:::

:::CodeblockTabs
Response

```json
{
  "access_token": "",
  "token_type": "Bearer",
  "expires_in": "",
  "scope": "all"
}
```
:::

:::BlockQuote
`access_token` is the token to use for further API calls, and `expires_in` is the number of seconds the token is valid for. The token should be passed as a HTTP Bearer token in the authorization header in further requests.
:::

**Errors:**

| HTTP Status Code | Error Code               | Description                                  |
| ---------------- | ------------------------ | -------------------------------------------- |
| 401              | invalid\_client          | Unsupported authentication method.           |
| 401              |                          | Completely missing authentication details.   |
| 400              | unsupported\_grant\_type | Unsupported "grant\_type" in request.        |
| 400              | invalid\_request         | Invalid or incorrectly supplied credentials. |
| 400              | missing\_client\_details | Credentials have not been supplied.          |

See also [Common Errors](https://docs.formedix.com/api/common-errors)

### Test an OAuth2 Bearer Token

This is a simple request to test that the HTTP Bearer token set in the authorization header is valid.

:::CodeblockTabs
Request

```HTTP
GET    {baseUrl}/fws/api/oauth/test
```
:::

:::BlockQuote
Example response:
:::

```json
{
  "ok": "good token"
}
```

See also [Common Errors](https://docs.formedix.com/api/common-errors)
