> For the complete documentation index, see [llms.txt](https://docs.enate.net/enate-help/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.enate.net/enate-help/enate-apis-and-webhooks/apis/api-authentication.md). # API Authentication Every call to the Operational API and the Configuration API has to carry a Bearer Token, apart from the request that gets you the token in the first place. This page covers how a token behaves once you have it: how long it lasts, what it's allowed to do, and what Enate returns when it refuses a request. Creating the Application Credential that you get a token from is covered on the Application Credentials page in the Builder section: {% content-ref url="/pages/Mb17Q8b06ZFCsOKaKgtN" %} [Application Credentials](/enate-help/builder/builder/user-management/application-credentials.md) {% endcontent-ref %} ## Getting a Token Swagger has built in support for getting a token. If you want to try the APIs, click the Authorize button on the Swagger page, enter the Application Credential's Client ID and Secret Key, and Swagger gets the token for you. Most API tools can do the same, because they support the OAuth 2.0 client credentials flow. In Postman, for example, set up the Authorization tab on a request or on a whole collection, and Postman gets the token and sends it for you. Use the token address below, and the Client ID and Secret Key from the Application Credential. From your own code, you get a token by sending the Client ID and Secret Key to the token address on your Enate platform. It's an OAuth 2.0 client credentials request, so the body is form encoded rather than JSON: ``` POST https://yourplatform/auth/oauth/token Content-Type: application/x-www-form-urlencoded grant_type=client_credentials&client_id=0f6c907b-00f4-4e12-8d75-41454b777533&client_secret= ``` Request a token once and reuse it until it stops working, rather than asking for a new one before every call. Requests to the token address count towards the allowance for sign-in and token requests, described under [Rate Limiting](/enate-help/enate-apis-and-webhooks/apis.md#rate-limiting) on the APIs page. ## Using a Token Once you've authorised in Swagger, Swagger sends the token with every request you try, so you don't need to add it yourself. A tool such as Postman does the same once its Authorization tab is set up. From your own code, send the token in the `Authorization` header of every request: ``` GET https://yourplatform/operational/Ticket/Get?ticketGUID=3f9a2c71-5b04-4e8d-a617-d20c94b8e153&api-version=4 Authorization: Bearer ``` A token is for one API. The Operational API accepts tokens issued for the Operational API, and the Configuration API accepts tokens issued for the Configuration API. A token presented to the other API is refused with a 401. ## How Long a Token Lasts The Authentication API tells you how long a token lasts when it issues it, and you can check the token's `exp` claim for the time it expires. A token is valid while it hasn't expired and the session behind it hasn't ended. Enate checks the session on every request. Two settings in the [General Settings](/enate-help/builder/builder/system-wide-settings/general-settings.md) section of Builder control the session: | Setting | What it does | | ------------------------ | ---------------------------------------------------------------------------------------------- | | Maximum Idle Duration | How long a token can go unused before it stops working. Each request counts as use. | | Maximum Session Duration | The longest a session can last, however active it is. If you leave it blank, there's no limit. | Both settings accept a value between 5 minutes and 25 hours and 1 minute. They're set for the whole Enate environment, so they apply to your integrations in the same way as they apply to your users. Changes to General Settings only take effect after a user logs out and in again. A request that changes data, a POST, always counts as use. A GET request counts too, but Enate records it at most once every 5 minutes. If you set Maximum Idle Duration to a few minutes and your integration only reads data, it can still reach the idle limit. A token also stops working immediately when any of these happens: * The Application Credential is deleted. * The Application Credential's secret is regenerated. This also invalidates the old Secret Key, so any integration still using it can't get a new token. * The Operational Role or Builder Role on the Application Credential is changed. * The user who created the Application Credential is deleted. * Any of these change on the user who created the Application Credential: their password, Username, User Type, Operational Role, Builder Role, Allowed Work Types, or the Only Single Sign-On User setting. This ends every session that user has, not just the credential's. When a token stops working, request a new one. A new token only has the roles the Application Credential has at that moment, so a role that has been removed isn't restored. Some changes don't end a token. Changing the credential's Expires On date only affects new tokens, because the date is checked when a token is requested. Changing the permissions inside a role takes effect on the next request, without a new token. An Application Credential also has an **Expires On** date, which can't be more than two years from the day you set it. Once that date has passed, the credential can't be used to get a token. ## What a Token Is Allowed to Do What a token can do comes from the roles on its Application Credential: * The **Operational Role** decides what the token can do in the Operational API. * The **Builder Role**, if the credential has one, decides what it can do in the Configuration API. Giving the Application Credential a different Operational Role or Builder Role ends the session, as described under How Long a Token Lasts, so you need a new token to pick up the change. Changing the permissions inside the role it already has takes effect on the next request. An endpoint that needs a permission the role doesn't include is refused with a 403 Forbidden. An Application Credential can't be given more than the person who creates it has. If you try to select a role that has permissions you don't have yourself, Enate refuses to save the credential. ### Work item access Application Credentials act on behalf of the user who created them, so they see the work items that user can see: * Asking for a single work item the user can't access returns 403 Forbidden with the message "Packet is not accessible by the authenticated user." * Searches and lists leave those work items out. They don't produce a 403. ### Credentials can't manage credentials The endpoints for creating and changing Application Credentials can only be called with a token from a signed-in user, not with a token that came from an Application Credential. A token from an Application Credential gets a 403 on them. This is why an integration can't create more credentials for itself. ### Live and test mode Live and test mode only apply to the Operational API, which is what Work Manager uses. Tokens for the Operational API belong to either live mode or test mode, and Enate only accepts a token at the address for its mode. A test mode token presented at the live address, or the other way round, is refused with a 401. The Configuration API doesn't have a test mode. The Test Mode page explains how test mode addresses work: {% content-ref url="/pages/-MWs9MKk-rUBXGd\_Zroh" %} [Testing Mode](/enate-help/work-manager/work-manager/test-mode.md) {% endcontent-ref %} A work item that belongs to the other mode from your token is refused with a 403 and the message "User is currently authenticated to work on Live Packets but requested Packet is not Live." for a live token, or the matching message for a test token. The reporting endpoints are only available in live mode, and return 403 in test mode. ## When Enate Refuses a Request A 401 or 403 response often has no body, so it doesn't tell you the reason. Use the table to see which checklist to follow. For the other status codes Enate returns, see [API Errors and Status Codes](/enate-help/enate-apis-and-webhooks/apis/api-errors-and-status-codes.md). | Situation | Status | What the response tells you | | ---------------------------------------------------------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------- | | No token, an expired token, a token that isn't valid, or a token for the other API | 401 Unauthorized | Nothing. Use the 401 checklist below. | | A token for the wrong mode | 401 Unauthorized | Nothing. Use the 401 checklist below. | | The credential's role doesn't include the permission the endpoint needs | 403 Forbidden | Nothing. Use the 403 checklist below. | | A credential token on an endpoint that manages Application Credentials | 403 Forbidden | Nothing. Use the 403 checklist below. | | A work item the user can't access | 403 Forbidden | The text "Packet is not accessible by the authenticated user." | | A work item that belongs to the other mode | 403 Forbidden | The text "User is currently authenticated to work on Live Packets but requested Packet is not Live." | ### If you get a 401 A 401 means Enate didn't accept the token. Check that: * The request has an `Authorization` header in the form `Authorization: Bearer `. * The token hasn't expired. Its `exp` claim gives the time it expires. * The session behind the token hasn't ended. It ends when the token goes unused for longer than the Maximum Idle Duration, when the Maximum Session Duration is reached, when the credential is deleted or its secret or roles change, and when the user who created it is deleted or their sign-in details or roles change. * The token is for the API you're calling. A token for the Operational API is refused by the Configuration API, and the other way round. * For the Operational API, the token is for the right mode. A test mode token is refused at the live address, and the other way round. In most of these cases the fix is to request a new token and send the request again. ### If you get a 403 A 403 means Enate accepted the token but won't allow the request. Check that: * The roles on the Application Credential include the permission the endpoint needs: the Operational Role for the Operational API, and the Builder Role for the Configuration API. * The endpoint isn't one that creates or changes Application Credentials. Those need a token from a signed-in user, not one from an Application Credential. * The user who created the Application Credential can access the work item the request names. * The work item belongs to the same mode as your token, live or test. * You're in live mode if you're calling a reporting endpoint. They return 403 in test mode. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.enate.net/enate-help/enate-apis-and-webhooks/apis/api-authentication.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.