docs: DOC-279: Access token page (#7137)

Co-authored-by: caitlinwheeless <[email protected]>
Co-authored-by: pakelley <[email protected]>

docs/source/guide/access_tokens.md

@@ -0,0 +1,134 @@
+---
+title: Access tokens
+short: Access tokens
+tier: enterprise
+type: guide
+order: 381
+order_enterprise: 359
+meta_title: Access tokens
+meta_description: Access tokens to interact with the Label Studio API and SDK. 
+section: "Manage Your Organization"
+date: 2025-02-18 12:03:59
+---
+
+Label Studio has personal access tokens and legacy tokens. The options available to users are set at the Organization level. Se [Access settings for orgs](#Access-token-settings-for-orgs) below. 
+
+<table>
+<thead>
+  <tr>
+    <th>Personal Access Token</th>
+    <th>Legacy Token</th>
+  </tr>
+  </thead>
+  <tr>
+  <td>
+    <ul>
+        <li>Have a TTL that can be set at the org level. (Label Studio Enterprise only)
+        <li>Are only visible to users once
+        <li>Can be manually revoked
+        <li>Require extra steps when used with HTTP API
+        <li>Only need to be set once when used SDK
+    </ul>
+  </td>
+  <td>
+    <ul>
+        <li>Does not expire
+        <li>Remains listed and available in your account settings
+        <li>Can be manually revoked
+        <li>Do not need to be refreshed with used with HTTP API
+        <li>Only need to be set once when used SDK
+    </ul>
+  </td>
+  </tr>
+</table>
+
+## Personal access tokens and the API
+
+### SDK
+
+Personal access tokens can be used with the Python SDK the same way in which legacy tokens were set:
+
+```python
+# Define the URL where Label Studio is accessible and the API key for your user account
+LABEL_STUDIO_URL = 'http://localhost:8080'
+# API key is available at the Account & Settings > Access Tokens page in Label Studio UI
+API_KEY = 'd6f8a2622d39e9d89ff0dfef1a80ad877f4ee9e3'
+
+# Import the SDK and the client module
+from label_studio_sdk.client import LabelStudio
+
+# Connect to the Label Studio API and check the connection
+ls = LabelStudio(base_url=LABEL_STUDIO_URL, api_key=API_KEY)
+
+```
+
+### HTTP API
+
+If you are interacting directly via HTTP, the personal access token functions as a JWT refresh token.
+
+You must use your personal access token (refresh token) to generate a short-lived access token. This access token is then used for API authentication.
+
+To generate this access token, make a POST request with your personal access token in the JSON body. For example:
+
+```bash
+curl -X POST <your-label-studio-url>/api/token/refresh \
+-H "Content-Type: application/json" \
+-d '{"refresh": "your-personal-access-token"}'
+```
+
+In response, you will receive a JSON payload similar to:
+
+```json
+{
+    "access": "your-new-access-token"
+}
+```
+
+Use this access token by including it in your API requests via the Authorization header:
+
+```http
+Authorization: Bearer your-new-access-token
+```
+
+When that access token expires (after around 5 minutes) you’ll get a 401 response, and will need to use your personal access token again to acquire a new one. This adds an extra layer of security.
+
+You can also check when the token is set to expire using the following script:
+
+```python
+# pip install pyjwt
+from datetime import datetime, timezone
+import jwt
+
+decoded = jwt.decode(token)
+exp = decoded.get("exp")
+token_is_expired = (exp <= datetime.now(timezone.utc).timestamp())
+```
+
+## Access token settings for orgs
+
+The options that are available to users depend on options selected at the organization level. 
+
+From the **Organization** page, click **Access Token Settings** in the upper right. 
+
+<div class="enterprise-only">
+
+!!! note
+    The **Organization** page is only available to users in the Admin and Owner role.
+
+</div>
+
+From here you can enable and disable token types. 
+
+* When a certain token type is disabled, existing tokens will not be able to authenticate to the Label Studio platform. 
+
+* Use the Personal Access Token Time-to-Live to set an expiration date for personal access tokens. This is only available for Label Studio Enterprise users. 
+
+
+![Screenshot of Access Token window](/images/admin/token-settings.png)
+
+
+## Finding your access token
+
+You can create/manage your access token from your [**Account & Settings** page](user_account) (click your username in the upper right in Label Studio). 
+
+

docs/source/guide/api.md

@@ -35,24 +35,13 @@ You must retrieve your access token so that you can authenticate to the API.
 
 1. In the Label Studio UI, click the user icon in the upper right.
 2. Click **Account & Settings**.
-3. Copy the access token. 
+3. Copy the access token. For more information, see [Access tokens](access_tokens). 
 
 In your first API call, specify the access token in the headers: 
 ```bash
-curl -X <method> <Label Studio URL>/api/<endpoint> -H 'Authorization: Token <token>'
+curl -X <method> <Label Studio URL>/api/<endpoint> -H 'Authorization: Bearer <token>'
 ```
 
-<div class="opensource-only">
-
-You can also retrieve the access token using the command line. 
-1. From the command line, run the following: 
-```bash
-label-studio user --username <username>
-```
-2. In the output returned in your terminal, the token for the user is listed as part of the user info.  
-
-</div>
-
 See [API documentation for authentication](https://api.labelstud.io/api-reference/introduction/getting-started#authentication).
 
 ### List all projects

docs/source/guide/sdk.md

@@ -41,7 +41,7 @@ The SDK provides a set of predefined classes and methods to interact with the La
    `pip install label-studio-sdk`
 2. In your Python script, do the following:
    - Import the SDK.
-   - Define your API key and Label Studio URL. The API key is available from your [**Account & Settings** page](user_account#Access-token).
+   - Define your API key and Label Studio URL. You can generate a key from your [**Account & Settings** page](user_account#Personal-access-token).
    - Connect to the API.
 ```python
 # Define the URL where Label Studio is accessible and the API key for your user account

docs/source/guide/user_account.md

@@ -17,7 +17,7 @@ To access your user account and settings, click your user icon in the upper righ
 ![Screenshot of the account and settings option](/images/admin/account_settings.png)
 
 
-## Account info
+## Personal info
 
 After you create an account in Label Studio, you can update the following:
 
@@ -28,16 +28,13 @@ After you create an account in Label Studio, you can update the following:
 
 Because your email address is your username, you cannot update it. If you need to change your email address, you will need to create a different user with the new email address. 
 
+## Email preferences 
 
-## Access token
-
-If you want to use the API, use this token to authenticate your API requests. 
+Use this section to opt out of Label Studio news and tips sent to your email address. 
 
-Click **Renew** to generate a new token. Any existing scripts using your old token will lose their authorization and will need to be updated to include your new token. 
+## Membership info
 
-## Active organization
-
-In this section, you can find information about your organization such as when it was created and the email address of the Owner (the user who initially created the Label Studio organization).
+In this section, you can find information about your organization, such as when the organization was created and the email address of the Owner (the user who initially created the Label Studio organization).
 
 <div class="enterprise-only">
 
@@ -51,7 +48,50 @@ You can also see a high-level summary of your contributions.
 
 </div>
 
+<div class="enterprise-only">
+
+## Personal access token
+
+!!! note
+    Whether this option appears depends on [settings at your organization level](access_tokens#Access-token-settings-for-orgs). 
+
+Click **Create** to generate an access token. When creating a token, ensure you save it somewhere secure, as it will only be visible one time. 
+
+While personal access tokens work seamlessly with the Label Studio SDK, if you are using HTTP API requests, you will need to take extra steps. See [Personal access tokens and the API](access_tokens#Personal-access-tokens-and-the-API). 
+
+</div>
+
+<div class="enterprise-only">
+
+You organization administrators may optionally set an expiration date for all personal access tokens. 
+
+</div>
+
+<div class="enterprise-only">
+
+## Legacy token
+
+!!! note
+    Whether this option appears depends on [settings at your organization level](access_tokens#Access-token-settings-for-orgs). 
+
+This token is pre-generated for you to use. Legacy tokens are easier to use for some API tasks, but are generally less secure. For more information, see [Access tokens](access_tokens).  
+
+Click **Renew** to generate a new token. Any existing scripts using your old token will lose their authorization and will need to be updated to include your new token. 
+
+</div>
+
+<div class="opensource-only">
+
+## Access token
+
+If you want to use the API, use this token to authenticate your API requests.
+
+Click **Renew** to generate a new token. Any existing scripts using your old token will lose their authorization and will need to be updated to include your new token. 
+
+</div>
+
+
+
+
 
-## Notifications
 
-Use this section to opt out of Label Studio news and tips sent to your email address.