Token system
A brief overview of what our most commonly used tokens are and how they work.
JWTs are credentials that can grant access to resources. Be careful where you paste them!
Refresh token
Validity: 2 WEEKS - see Example refresh token
Refresh tokens are weak authentication tokens that have no other purpose than being used to refresh an access token once it has expired. If a refresh token expires, the user has to re-login using his credentials so that a new refresh token is generated.
For more information, see this endpoint.
Access token
Validity: 20 MINUTES - see Example access token
Access tokens are used as the main method of authentication for all Embloy services. Access tokens can be generated using a valid refresh token and are only valid for their defined scope.
Access token scopes determine the permissions of the token. They need to align with the base URL of the application and the path being requested. For instance, a token with the scope genius.embloy.com/api.write cannot access services at api.embloy.com because the base URL doesn't match. Similarly, a token with the scope api.embloy.com/api.write can access all endpoints under the /api path of the api.embloy.com service, but it can't be used to request the path /abc/xyz. Lastly, the operations allowed on an endpoint are either write or read. Make sure the scope has the appropriate permissions for the HTTP method you want to use (read only allows GET requests, while write allows all request methods).
For more information, see this endpoint.
Client token
Validity: 3 MONTHS (by default, but can be customized) - see Example client token
Client tokens can be seen as an Embloy-API token, which a client needs to have in order to use Embloy's SDKs. The purpose of the client token is to transmit a client's ID and subscription tier when generating request tokens.
Whenever you change your subscription plan, you will have to update your client token(s) to access the newly subscribed features.
For more information, see this endpoint.
Request token
Validity: 30 MINUTES - see Example request token (minimum payload) and Example request token (maximum payload)
Request tokens can be generated using a valid client token and act as confirmation that a job posting using the "Apply with EMBLOY" button is really verified and connected to Embloy. Therefore, whenever a user presses on "Apply with EMBLOY", a request to the client's server is made to generate a new request token for the given job with the secret client token.
When a request token is generated, it can be used to submit an application for a given job. Every request token saves the owner's ID (=client) and information about the job for which it is used, as well as information related to the requested application session, such as the success_url, cancel_url and more.
The only required field to create a request token is job_slug which is used to identify a client's job, which is not known to Embloy yet. All other fields are optional and can be used to customize the application process. See also the token customization documentation.
For more information, see this endpoint.
Genius-Query token
Validity: 1 day (by default, but customizable up to a year)
Genius-Query tokens can be generated by all subscribed users either through the Genius dashboard or manually using an access token. A valid token grants access to specific resources for a defined duration..
For a comparison between Genius-Query and Quicklink, refer to the scenario comparison.
Genius-Query tokens resemble request tokens but offer additional flexibility. Unlike request tokens, which are generated when a user applies via Quicklink and are only valid for a short amount of time, Genius-Query tokens can be tailored with a custom expiration date and are capable of accessing specific resources (such as a job, account, or application) rather than just jobs.
For more information, see this endpoint.
Password-reset token
Validity: 15 minutes
If you forgot your password and want to reset it manually, you will need a password-reset token, which is included in the password reset email we sent you.
For more information, see this endpoint.
Activation token
Validity: 1 day
When you create a new account manually (= without using any of the provided OAuth options), you will have to confirm your email before being able to access any Embloy services. An email including the activation token is automatically sent to your account's email-address after account creation.
If you did not activate your account and your activation token has expired, you can request a new activation token here.
For more information, see this endpoint and this endpoint.