> For the complete documentation index, see [llms.txt](https://docs.cybus.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cybus.io/access/security/json-web-tokens.md). # JSON Web Tokens Generate long-lived JSON Web Tokens (JWT) to authenticate API requests and automate tasks in Connectware. JSON Web Tokens (JWT) allow you to authenticate API requests, automate tasks, and securely access Connectware resources. These tokens can be configured as long-lived tokens that remain valid for extended periods, making them ideal for ongoing automation and continuous system access. Learn how to generate tokens, apply security best practices, and understand the protections built into Connectware's authentication system. ## Token Security Protect your authentication tokens through secure configuration and applying best practices. ### Token Redirection Rules Connectware enforces strict URL redirection rules to prevent phishing attempts and protect against web security vulnerabilities. 1. **Protocol binding:** Connectware requires HTTPS and ensures that no redirects can downgrade the connection to HTTP. 2. **Domain restriction:** Redirects are limited to the current domain. * Example: When accessing `https://demo.cybus.io/`, you can only redirect to paths within that domain. Redirects to external domains like `https://cybus.io/` are blocked. {% hint style="warning" %} JSON web tokens provide access to Connectware with the same permissions as the user who generated it. Tokens should be generated by users with only the required permission levels. {% endhint %} ### Token Best Practices Implementing secure token practices is crucial for maintaining the security of your Connectware environment. Below are key practices to follow when working with tokens: 1. **Set appropriate expiration** * Configure token lifetime using the `expireTimeInHours` parameter based on your specific use case. * Avoid unnecessarily long expiration periods. 2. **Implement token rotation** * Replace active tokens regularly with new ones. * Revoke old tokens after replacement. 3. **Separate token usage** * Create distinct tokens for different services or tasks. * This limits potential security exposure if any single token is compromised. ## Generating JSON Web Tokens The user needs the **Token** [authentication method](/access/user-management/users.md#authentication-methods). Without it, `POST /api/login` still returns a token, but every request that uses the token fails with `401 Unauthorized`. See [Enabling Token Authentication for a User](#enabling-token-authentication-for-a-user). 1. Send a POST request to obtain your token. The response will contain a token property with your JWT authentication credentials. {% code lineNumbers="true" %} ```yaml curl -X 'POST' \ 'https:///api/login' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -k \ -d '{ "username": "", "password": "", "expireTimeInHours": 99999, "label": "test-token" }' ``` {% endcode %} 2. Use this token in subsequent requests by adding it as an `apiToken` query string parameter in your URLs. {% code lineNumbers="true" %} ```yaml curl -k --location --request GET https:///api/users?apiToken= ``` {% endcode %} ## Enabling Token Authentication for a User Users that you create in the Admin UI have the **Token** authentication method by default. To add it to an existing user in the Admin UI, see [Changing Authentication Methods](/access/user-management/users.md#changing-authentication-methods). When you create a user through `POST /api/users`, the user gets only the methods that you list in the `grantTypes` property, and none if you leave it out. Include `token`, and set `isRequired` to `false` so that either method on its own is enough to authenticate: {% code lineNumbers="true" %} ```json { "username": "api-client", "password": "${PASSWORD}", "identityProvider": "local", "grantTypes": [ { "method": "password", "isRequired": false }, { "method": "token", "isRequired": false } ] } ``` {% endcode %} Replace `${PASSWORD}` with the password for the new user. To update an existing user through the API, send the same `grantTypes` list with `PUT /api/users/${USER_ID}`, where `${USER_ID}` is the ID of the user. The list replaces all existing methods of the user, so include every method that the user needs. ## Browser Authentication via JSON Web Tokens You can use tokens to authenticate users via an authentication URL or redirect users to a specific location within Connectware after authentication. * **Authentication URL:** To authenticate users on the browser using the token, enter the following URL: {% code lineNumbers="true" %} ```yaml https:///admin?apiToken= ``` {% endcode %} * **Authentication with Redirection:** To redirect users to a specific location within Connectware after authentication, enter the following URL. This is particularly useful when working with [Cybus::IngressRoute](/data-flows/service-commissioning-files/resources/cybus-ingressroute.md) resources. {% code lineNumbers="true" %} ```yaml https:///admin?redirect=&apiToken= ``` {% endcode %} **Example** {% code lineNumbers="true" %} ```yaml https:///admin?redirect=/services/foo/bar&apiToken=barFoo ``` {% endcode %} --- # 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.cybus.io/access/security/json-web-tokens.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.