Authentication
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.
Authentication request endpoint:
POST {baseUrl}/fws/api/oauth/tokenYou can supply your company's client_id and client_secret credentials to authenticate an OAuth2 session using one of the following three methods:
- 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.
- Providing the credentials as client_id and client_secret body parameters in a application/x-www-form-urlencoded request.*
- Providing the credentials as client_id and client_secret properties in a JSON body for a application/json request (see example request aside).*
Example authentication request as application/json body:
{
"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.
The example request above returns the following response:
{
"access_token": "",
"token_type": "Bearer",
"expires_in": "",
"scope": "all"
}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
Test an OAuth2 Bearer Token
This is a simple request to test that the HTTP Bearer token set in the authorization header is valid.
GET {baseUrl}/fws/api/oauth/testExample response:
{
"ok": "good token"
}See also Common Errors
