Assemble has a wide range of API endpoints, from viewing public opportunities to updating users. Depending on the API endpoint you are using, you may need to authenticate before you can perform a particular request.
Assemble supports JSON Web Tokens as a way to authorise requests and to determine the acting user.
To create a JSON Web Token, you must first generate a pre-authentication token, you can then use the pre-authentication token to create a JSON Web Token; if the user has two factor authentication, the two factor key must be provided when generating a new JSON Web Token.
The JSON Web Token can be used by setting it as the authorisation bearer within the header of the request.
Once you have a JSON Web Token, you do not have to re-generate a pre-authentication token when the JSON Web Token expires, you can simply refresh your existing one.
The Authentication API documentation can be found here.
JSON Web Token (JWT) is an open standard that defines a compact and self-contained way for securely transmitting information between parties as a JSON object (https://jwt.io/).
Once you have created a JWT, each subsequent request should include the JWT within the header of the request as an authorisation bearer, allowing you to access routes, services, and resources that are permitted with that token.
A pre-authentication token is a temporary token which is generated from a set of credentials and then can be used to create a JSON Web Token.
You must provide the email address and password of the user which you are trying to authenticate to the /auth/api/ endpoint.
The pre-authentication token endpoint will either return you a token to be used when creating a JWT or a validation error due to an incorrect email or password.
If the user that is generating the pre-authentication token has two facator authentication enabled, Assemble will automatically trigger the users preferred two factor method (i.e email) so that the authentication key can be used when creating a JSON Web Token.
Please click here to view the pre-authentication token endpoint documentation.
Once you have successfully generated a pre-authentication token, you can now use the token to create your JWT via the /auth/api/token endpoint.
Assemble supports two factor authentication and this is also enforced through the API. When creating your JWT using the pre-authentication token, you may also need to provide the two factor key within the body of the request.
Optionally, you can also specifiy if you would like the receive the "minimal" version of the JWT which will minimise the size of the token and exclude certain information from the JWT payload. Assemble will accept both the minimal and normal JWT when authenticating.
The creating JSON Web Token endpoint will either return a new JWT for you to use when authenticating or an error if you provided a invalid pre-authentication token or two factor key.
Please click here to view the creating JSON Web token endpoint documentation.
Now that you have a JWT, you can use this token to authenticate within the Assemble API.
Assemble expects the JSON Web token to be present in the header of the request as the authorisation bearer.
For example;
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwiZGlzcGxheV9uYW1lIjoiSm9obiBEb2UiLCJpYXQiOjE1MTYyMzkwMjJ9.Boca2nntRviOO8IdiP4CZPnMmwZZ5be4Zoen60PswDo
Your JWT will expire periodically and you will have to refresh your JWT to re-authenticate.
You will know if your JSON Web Token has expired as the request you sent to an authenticated endpoint will respond with a "401" HTTP status code and a messaging stating "Token has expired". In this case, all you need to do is send a request to the /auth/api/refresh endpoint with the JWT in the body of the request. This endpoint will respond with a new JWT that you can put into the header of your previous request and resend.
You cannot refresh a single JWT more than one time, if you try refreshing the same JWT, that token will become blacklisted and you will have to create a new pre-authentication token to generate a new JWT.
Please click here to view the creating JSON Web token endpoint documentation.
The JSON Web Token will include a payload that can be decoded to view certain information about the user. This information will change depending on if the token is the "minimal" version. However, the payload will always include the basic information about the authenticated user.
You can use existing packages such as jwt-decode to decode your JSON Web Token.
To find out more about the Authentication API, click here.