You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
-[Option 1: Official Box CLI App (Recommended)](#option-1-official-box-cli-app-recommended)
13
+
-[Option 2: Your Own Custom App](#option-2-your-own-custom-app)
14
+
-[Supported Ports](#supported-ports)
15
+
-[Additional Flags](#additional-flags)
16
+
-[Reauthorize OAuth2](#reauthorize-oauth2)
13
17
14
18
15
19
Ways to Authenticate
16
20
--------------------
17
21
18
22
### Developer Token
19
23
20
-
The fastest way to get started using the API is with developer tokens. A
21
-
developer token is simply a short-lived access token that cannot be refreshed
22
-
and can only be used with your own account. Therefore, they're only useful for
23
-
testing an app and aren't suitable for production. You can obtain a developer
24
-
token from your application's
25
-
[developer console][dev-console] page.
24
+
A developer token is a token that you can generate directly from the [Box Developer Console][dev-console]. It provides a quick way to test API calls without setting up a full authentication flow.
26
25
27
-
You can pass dev token to any cli command by using `--token` flag
> **Tip:** You can generate a new developer token at any time from the **Configuration** tab of your application in the [Developer Console][dev-console].
34
41
35
42
### Server Auth with JWT
36
43
37
-
Server auth allows your application to authenticate itself with the Box API
38
-
for a given enterprise. By default, your application has a
that represents it and can perform API calls. The Service Account is separate
41
-
from the Box accounts of the application developer and the enterprise admin of
42
-
any enterprise that has authorized the app — files stored in that account are
43
-
not accessible in any other account by default, and vice versa.
44
+
JSON Web Token (JWT) authentication allows your application to authenticate as a [Service Account](https://developer.box.com/platform/user-types#service-account) without requiring user interaction. This is ideal for server-to-server integrations, automated workflows, and backend services.
45
+
46
+
**Key characteristics:**
44
47
45
-
If you generated your public and private keys automatically through the
46
-
[Box Developer Console][dev-console], you can use the JSON file created there
47
-
to configure the SDK and create an environment to make calls as the
48
-
Service Account:
48
+
- The application authenticates on behalf of a **Service Account**, which is separate from any individual user's account.
49
+
- Files stored in the Service Account are not accessible from other accounts by default, and vice versa.
50
+
- Requires a public/private key pair, which can be generated automatically in the [Developer Console][dev-console].
51
+
52
+
**Setup:**
53
+
54
+
1. In the [Developer Console][dev-console], create or open an application that uses **JWT** authentication.
55
+
2. Generate a public/private key pair (or upload your own). This produces a JSON configuration file.
56
+
3. Download the configuration file and add it as an environment:
that represents it and can perform API calls. The Service Account is separate
68
-
from the Box accounts of the application developer and the enterprise admin of
69
-
any enterprise that has authorized the app — files stored in that account are
70
-
not accessible in any other account by default, and vice versa.
72
+
Client Credentials Grant (CCG) authentication allows your application to authenticate as a [Service Account](https://developer.box.com/platform/user-types#service-account) using a **Client ID**, **Client Secret**, and **Enterprise ID**. Like JWT, this method is designed for server-to-server communication and does not require user interaction.
71
73
72
-
Adding a CCG environment is a similar process to adding a JWT environment. However, you must manually create a configuration file.
73
-
This file should contain `clientID`, `clientSecret` and `enterpriseId`. You can find this information in the [Box Developer Console][dev-console].
74
+
**Key characteristics:**
74
75
75
-
Example configuration file:
76
+
- The application authenticates on behalf of a **Service Account**, which is separate from any individual user's account.
77
+
- Files stored in the Service Account are not accessible from other accounts by default, and vice versa.
78
+
- No key pair generation is needed — authentication relies on the Client ID and Client Secret only.
79
+
80
+
**Setup:**
81
+
82
+
1. In the [Developer Console][dev-console], create or open an application that uses **Client Credentials Grant** authentication.
83
+
2. Create a JSON configuration file with the following structure:
76
84
77
85
```json
78
86
{
79
87
"boxAppSettings": {
80
-
"clientID": "myClientId",
81
-
"clientSecret": "mySecret"
88
+
"clientID": "your_client_id",
89
+
"clientSecret": "your_client_secret"
82
90
},
83
-
"enterpriseID": "myEnterpriseId"
91
+
"enterpriseID": "your_enterprise_id"
84
92
}
85
93
```
86
94
87
-
Then create a new environment with `--ccg-auth` flag and point it to the configuration file
95
+
> **Tip:** You can find the `clientID` and `clientSecret` values in the **Configuration** tab, and the `enterpriseID` in the **General Settings** tab of your application in the [Developer Console][dev-console].
96
+
97
+
3. Add the environment with the `--ccg-auth` flag:
Remember to set your current environment to the proper one
103
+
4. If you have multiple environments, set the active one:
94
104
95
105
```bash
96
106
box configure:environments:set-current
97
107
```
98
108
99
-
An environment for making calls as an App User or Managed User can be created just like a Service Account environment. You need to pass an additional `--ccg-user` flag with `userId` as the value
109
+
**Authenticating as a specific user:**
110
+
111
+
By default, CCG authenticates as the Service Account. To make API calls as an App User or Managed User instead, pass the `--ccg-user` flag with the user's ID:
Refer to the [OAuth Guide](https://developer.box.com/guides/cli/quick-start) if you want to use OAuth2.
119
+
The `box login` command authenticates you with Box using OAuth 2.0. It starts a local callback server, opens your browser for authorization, and stores the resulting tokens in a named environment.
108
120
109
-
#### Reauthorize OAuth2
121
+
When you run `box login`, the CLI presents two login options: the **Official Box CLI App** and a **custom app** you create yourself. You can either choose interactively or skip the selection entirely using the `--default-box-app` (`-d`) flag.
122
+
123
+
#### Option 1: Official Box CLI App (Recommended)
110
124
111
-
After each successful OAuth2 authorization, a pair of tokens is generated, the Access Token and Refresh Token.
125
+
This is the fastest way to get started with Box CLI. No app creation in the Box Developer Console is required — just run the command and authorize.
112
126
113
-
The first one, the [Access Token](https://developer.box.com/guides/authentication/tokens/access-tokens/), is used to represent the authenticated user to the Box servers and is valid for 60 minutes.
127
+
**Interactive selection** — run `box login` and press **Enter** at the Client ID prompt to use the built-in app:
128
+
129
+
```bash
130
+
box login
131
+
# When prompted for a Client ID, press Enter to use the Official Box CLI App.
132
+
```
114
133
115
-
The second one, the [Refresh Token](https://developer.box.com/guides/authentication/tokens/refresh/), is used to refresh the Access Token when it has expired or is close to expiring. A Refresh Token is valid for 1 use within 60 days.
134
+
**Skip the prompt** — use the `--default-box-app` (or `-d`) flag to go directly to authorization:
116
135
117
-
However, it may happen that both mentioned tokens, `Access Token` and `Refresh Token`, have expired. You may then see following error:
136
+
```bash
137
+
box login --default-box-app
138
+
```
118
139
119
140
```bash
120
-
Your refresh token has expired.
141
+
box login -d
142
+
```
143
+
144
+
> **Note:** The Official Box CLI App uses scopes limited to content actions, which allows you to effectively manage your files and folders. If you need broader scopes (e.g., managing users, groups, or enterprise settings), use your own custom app instead.
145
+
146
+
#### Option 2: Your Own Custom App
147
+
148
+
If you need customized scopes or a dedicated application, you can log in with your own OAuth app. When prompted, enter the **Client ID** and **Client Secret** from your application's configuration.
149
+
150
+
Before running the command, set up the app in the [Box Developer Console](https://cloud.app.box.com/developers/console):
151
+
152
+
1. Select an application with **OAuth 2.0 user authentication** (or create a new Custom App).
153
+
2. In the **Configuration** tab, set the **Redirect URI** to `http://localhost:3000/callback` (adjust the port if you use a different `--port` value).
154
+
3. Click **Save Changes**.
155
+
156
+
Then log in:
157
+
158
+
```bash
159
+
box login
160
+
# When prompted, enter your Client ID and Client Secret.
161
+
```
162
+
163
+
For a step-by-step walkthrough, see the [Quickstart Guide](https://developer.box.com/guides/tooling/cli/quick-start/).
164
+
165
+
#### Supported Ports
166
+
167
+
The `box login` command starts a local callback server to receive the OAuth redirect. You can control the port with the `--port` (`-p`) flag. The default port is **3000**.
168
+
169
+
When using the **Official Box CLI App**, only the following ports are supported:
170
+
171
+
| Port | Command |
172
+
|------|---------|
173
+
| 3000 |`box login -d` (default) |
174
+
| 3001 |`box login -d --port 3001`|
175
+
| 4000 |`box login -d --port 4000`|
176
+
| 5000 |`box login -d --port 5000`|
177
+
| 8080 |`box login -d --port 8080`|
178
+
179
+
When using your own custom app, any port can be used — just make sure the **Redirect URI** in the Developer Console matches `http://localhost:<port>/callback`.
180
+
181
+
#### Additional Flags
182
+
183
+
| Flag | Short | Description |
184
+
|------|-------|-------------|
185
+
|`--default-box-app`|`-d`| Use the Official Box CLI App and proceed directly to authorization. |
186
+
|`--port <number>`|`-p`| Set the port for the local callback server. Default: `3000`. |
187
+
|`--name <string>`|`-n`| Set a name for the environment. Default: `oauth`. |
188
+
|`--reauthorize`|`-r`| Reauthorize an existing environment (requires `--name`). |
189
+
|`--code`|`-c`| Manually visit the authorize URL and input the auth code. |
190
+
|`--incognito-browser`|`-i`| Open the authorize URL in a private/incognito browser window. |
191
+
192
+
#### Reauthorize OAuth2
193
+
194
+
After each successful OAuth 2.0 authorization, a pair of tokens is generated: an **Access Token** and a **Refresh Token**.
195
+
196
+
- The [Access Token](https://developer.box.com/guides/authentication/tokens/access-tokens/) represents the authenticated user and is valid for **60 minutes**.
197
+
- The [Refresh Token](https://developer.box.com/guides/authentication/tokens/refresh/) is used to obtain a new Access Token. It is valid for **1 use within 60 days**.
198
+
199
+
If both tokens expire, you will see the following error:
200
+
201
+
```
202
+
Your refresh token has expired.
121
203
Please run this command "box login --name <ENVIRONMENT_NAME> --reauthorize" to reauthorize selected environment and then run your command again.
122
204
```
123
205
124
-
In this case, you need to log in again to obtain required tokens by using the following command:
206
+
To reauthorize, run:
125
207
126
208
```bash
127
209
box login --name "ENVIRONMENT_NAME" --reauthorize
128
210
```
129
211
130
-
where `ENVIRONMENT_NAME` is the name of the environmentto be reauthorized.
212
+
The `--reauthorize` flag retrieves the existing `clientID` and `clientSecret` from the stored environment, so you do not need to enter them again. After a successful login, the environment is updated and set as the default.
131
213
132
-
Thanks to the `--reauthorize`flag, the `clientID` and `clientSecret` parameters will be retrieved from the existing environment instead of asking the user for them.
214
+
You can also combine `--reauthorize`with `--default-box-app` to switch an existing environment to the Official Box CLI App:
133
215
134
-
After a successful login, the `ENVIRONMENT_NAME` environment will be updated and set as the default.
Sign in with OAuth and set a new environment or update an existing if reauthorize flag is used
4
+
Sign in with OAuth 2.0 and create a new environment (or update an existing one with --reauthorize).
5
+
6
+
Login options:
7
+
8
+
(1) Official Box CLI App
9
+
No app setup needed. Use --default-box-app (-d) to skip the prompt.
10
+
11
+
(2) Your own custom OAuth app
12
+
Enter your Client ID and Client Secret when prompted.
13
+
14
+
Quickstart: run "box login -d" to sign in immediately. A browser window will open for authorization. Once access is granted, the environment is created and set as default — you can start running commands right away.
5
15
6
16
*[`box login`](#box-login)
7
17
8
18
## `box login`
9
19
10
-
Sign in with OAuth and set a new environment or update an existing if reauthorize flag is used
20
+
Sign in with OAuth 2.0 and create a new environment (or update an existing one with --reauthorize).
0 commit comments