Skip to content

Commit d3e5a27

Browse files
caitlinwheelesscaitlinwheelesspakelley
authored
docs: DOC-279: Access token page (#7137)
Co-authored-by: caitlinwheeless <[email protected]> Co-authored-by: pakelley <[email protected]>
1 parent 48fcae9 commit d3e5a27

File tree

5 files changed

+187
-24
lines changed

5 files changed

+187
-24
lines changed

‎docs/source/guide/access_tokens.md

+134
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
---
2+
title: Access tokens
3+
short: Access tokens
4+
tier: enterprise
5+
type: guide
6+
order: 381
7+
order_enterprise: 359
8+
meta_title: Access tokens
9+
meta_description: Access tokens to interact with the Label Studio API and SDK.
10+
section: "Manage Your Organization"
11+
date: 2025-02-18 12:03:59
12+
---
13+
14+
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.
15+
16+
<table>
17+
<thead>
18+
<tr>
19+
<th>Personal Access Token</th>
20+
<th>Legacy Token</th>
21+
</tr>
22+
</thead>
23+
<tr>
24+
<td>
25+
<ul>
26+
<li>Have a TTL that can be set at the org level. (Label Studio Enterprise only)
27+
<li>Are only visible to users once
28+
<li>Can be manually revoked
29+
<li>Require extra steps when used with HTTP API
30+
<li>Only need to be set once when used SDK
31+
</ul>
32+
</td>
33+
<td>
34+
<ul>
35+
<li>Does not expire
36+
<li>Remains listed and available in your account settings
37+
<li>Can be manually revoked
38+
<li>Do not need to be refreshed with used with HTTP API
39+
<li>Only need to be set once when used SDK
40+
</ul>
41+
</td>
42+
</tr>
43+
</table>
44+
45+
## Personal access tokens and the API
46+
47+
### SDK
48+
49+
Personal access tokens can be used with the Python SDK the same way in which legacy tokens were set:
50+
51+
```python
52+
# Define the URL where Label Studio is accessible and the API key for your user account
53+
LABEL_STUDIO_URL = 'http://localhost:8080'
54+
# API key is available at the Account & Settings > Access Tokens page in Label Studio UI
55+
API_KEY = 'd6f8a2622d39e9d89ff0dfef1a80ad877f4ee9e3'
56+
57+
# Import the SDK and the client module
58+
from label_studio_sdk.client import LabelStudio
59+
60+
# Connect to the Label Studio API and check the connection
61+
ls = LabelStudio(base_url=LABEL_STUDIO_URL, api_key=API_KEY)
62+
63+
```
64+
65+
### HTTP API
66+
67+
If you are interacting directly via HTTP, the personal access token functions as a JWT refresh token.
68+
69+
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.
70+
71+
To generate this access token, make a POST request with your personal access token in the JSON body. For example:
72+
73+
```bash
74+
curl -X POST <your-label-studio-url>/api/token/refresh \
75+
-H "Content-Type: application/json" \
76+
-d '{"refresh": "your-personal-access-token"}'
77+
```
78+
79+
In response, you will receive a JSON payload similar to:
80+
81+
```json
82+
{
83+
"access": "your-new-access-token"
84+
}
85+
```
86+
87+
Use this access token by including it in your API requests via the Authorization header:
88+
89+
```http
90+
Authorization: Bearer your-new-access-token
91+
```
92+
93+
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.
94+
95+
You can also check when the token is set to expire using the following script:
96+
97+
```python
98+
# pip install pyjwt
99+
from datetime import datetime, timezone
100+
import jwt
101+
102+
decoded = jwt.decode(token)
103+
exp = decoded.get("exp")
104+
token_is_expired = (exp <= datetime.now(timezone.utc).timestamp())
105+
```
106+
107+
## Access token settings for orgs
108+
109+
The options that are available to users depend on options selected at the organization level.
110+
111+
From the **Organization** page, click **Access Token Settings** in the upper right.
112+
113+
<div class="enterprise-only">
114+
115+
!!! note
116+
The **Organization** page is only available to users in the Admin and Owner role.
117+
118+
</div>
119+
120+
From here you can enable and disable token types.
121+
122+
* When a certain token type is disabled, existing tokens will not be able to authenticate to the Label Studio platform.
123+
124+
* 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.
125+
126+
127+
![Screenshot of Access Token window](/images/admin/token-settings.png)
128+
129+
130+
## Finding your access token
131+
132+
You can create/manage your access token from your [**Account & Settings** page](user_account) (click your username in the upper right in Label Studio).
133+
134+

‎docs/source/guide/api.md

+2-13
Original file line numberDiff line numberDiff line change
@@ -35,24 +35,13 @@ You must retrieve your access token so that you can authenticate to the API.
3535

3636
1. In the Label Studio UI, click the user icon in the upper right.
3737
2. Click **Account & Settings**.
38-
3. Copy the access token.
38+
3. Copy the access token. For more information, see [Access tokens](access_tokens).
3939

4040
In your first API call, specify the access token in the headers:
4141
```bash
42-
curl -X <method> <Label Studio URL>/api/<endpoint> -H 'Authorization: Token <token>'
42+
curl -X <method> <Label Studio URL>/api/<endpoint> -H 'Authorization: Bearer <token>'
4343
```
4444

45-
<div class="opensource-only">
46-
47-
You can also retrieve the access token using the command line.
48-
1. From the command line, run the following:
49-
```bash
50-
label-studio user --username <username>
51-
```
52-
2. In the output returned in your terminal, the token for the user is listed as part of the user info.
53-
54-
</div>
55-
5645
See [API documentation for authentication](https://api.labelstud.io/api-reference/introduction/getting-started#authentication).
5746

5847
### List all projects

‎docs/source/guide/sdk.md

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

‎docs/source/guide/user_account.md

+50-10
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ To access your user account and settings, click your user icon in the upper righ
1717
![Screenshot of the account and settings option](/images/admin/account_settings.png)
1818

1919

20-
## Account info
20+
## Personal info
2121

2222
After you create an account in Label Studio, you can update the following:
2323

@@ -28,16 +28,13 @@ After you create an account in Label Studio, you can update the following:
2828

2929
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.
3030

31+
## Email preferences
3132

32-
## Access token
33-
34-
If you want to use the API, use this token to authenticate your API requests.
33+
Use this section to opt out of Label Studio news and tips sent to your email address.
3534

36-
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.
35+
## Membership info
3736

38-
## Active organization
39-
40-
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).
37+
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).
4138

4239
<div class="enterprise-only">
4340

@@ -51,7 +48,50 @@ You can also see a high-level summary of your contributions.
5148

5249
</div>
5350

51+
<div class="enterprise-only">
52+
53+
## Personal access token
54+
55+
!!! note
56+
Whether this option appears depends on [settings at your organization level](access_tokens#Access-token-settings-for-orgs).
57+
58+
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.
59+
60+
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).
61+
62+
</div>
63+
64+
<div class="enterprise-only">
65+
66+
You organization administrators may optionally set an expiration date for all personal access tokens.
67+
68+
</div>
69+
70+
<div class="enterprise-only">
71+
72+
## Legacy token
73+
74+
!!! note
75+
Whether this option appears depends on [settings at your organization level](access_tokens#Access-token-settings-for-orgs).
76+
77+
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).
78+
79+
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.
80+
81+
</div>
82+
83+
<div class="opensource-only">
84+
85+
## Access token
86+
87+
If you want to use the API, use this token to authenticate your API requests.
88+
89+
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.
90+
91+
</div>
92+
93+
94+
95+
5496

55-
## Notifications
5697

57-
Use this section to opt out of Label Studio news and tips sent to your email address.

‎docs/themes/v2/source/images/admin/token-settings.png

74.6 KB
Loading

0 commit comments

Comments
 (0)