Skip to content

Commit a646375

Browse files
authored
Add PAT usage documentation (#9959)
1 parent ef27ba7 commit a646375

File tree

2 files changed

+78
-0
lines changed

2 files changed

+78
-0
lines changed

site/content/en/docs/api_sdk/access_tokens.md

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -140,3 +140,26 @@ be restored.
140140

141141
The token will not be available for use anymore.
142142

143+
## How to use Personal Access Tokens
144+
145+
Once you have a Personal Access Token, it can be used for authentication in CVAT.
146+
147+
To authenticate a server HTTP API request with a token, the `Authorization` header
148+
must be specified. The value has to include the `Bearer` prefix:
149+
`Authorization: Bearer token_value`.
150+
151+
Example: sending a request via the _requests_ Python library
152+
```python
153+
import requests
154+
token = "..."
155+
response = requests.get(
156+
"https://app.cvat.ai/api/tasks",
157+
headers={"Authorization": "Bearer " + token}
158+
)
159+
print(response.json()["results"])
160+
```
161+
162+
Personal Access Tokens can also be used for authentication in other CVAT components:
163+
- in the {{< ilink "/docs/api_sdk/sdk/lowlevel-api#authentication" "low-level" >}} and
164+
{{< ilink "/docs/api_sdk/sdk/highlevel-api#authentication" "high-level" >}} API of the CVAT SDK
165+
- in the {{< ilink "/docs/api_sdk/cli#authentication" "CVAT CLI" >}}

site/content/en/docs/api_sdk/cli/_index.md

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,61 @@ for example, `cvat-cli ls` works the same way as `cvat-cli task ls`. These
7272
aliases are provided for backwards compatibility and are deprecated.
7373
Use the `task <action>` form instead.
7474

75+
### Authentication
76+
77+
CLI supports 2 authentication options:
78+
- Personal Access Token (PAT) authentication, with an access token value
79+
- Password authentication, with a username and a password
80+
81+
Personal Access Token (PAT) authentication requires a token that can be configured
82+
in the user settings section in the UI. It is the recommended authentication option
83+
for most clients. {{< ilink "/docs/api_sdk/access_tokens" "Read more." >}}
84+
85+
Password authentication requires a username and password pair. For better security it's
86+
recommended to use a Personal Access Token (PAT) instead, if possible.
87+
88+
{{< tabpane text=true >}}
89+
90+
{{%tab header="Personal Access Token (PAT) authentication" %}}
91+
92+
A Personal Access Token can only be used via the `CVAT_ACCESS_TOKEN` environment variable.
93+
This variable is prioritized over other environment variables used for authentication.
94+
95+
```bash
96+
export CVAT_ACCESS_TOKEN="token value"
97+
cvat-cli task ls
98+
```
99+
100+
{{% /tab %}}
101+
102+
{{%tab header="Password authentication" %}}
103+
104+
Credentials can be specified via the `--auth` global CLI parameter. The password can
105+
be passed after the colon (`:`) separator or via the `PASS` environment variable.
106+
For better security, it's recommended to use the `PASS` environment variable or
107+
Personal Access Tokens.
108+
109+
```bash
110+
cvat-cli --auth "username:password" task ls
111+
```
112+
113+
```bash
114+
export PASS="password"
115+
cvat-cli --auth "username" task ls
116+
```
117+
118+
The `--auth` parameter can also be omitted. In this case, the CLI will try to use the current
119+
OS user as the username. If the `PASS` environment variable is configured, it's value will be used
120+
for the password. Otherwise, the password will be requested for input.
121+
122+
```bash
123+
cvat-cli task ls
124+
```
125+
126+
{{% /tab %}}
127+
128+
{{< /tabpane >}}
129+
75130
## Examples - tasks
76131

77132
### Create

0 commit comments

Comments
 (0)