Get started with the Box Python SDK, using OAuth 2.0 in under 3 minutes
I was looking for a way to get developers started using the Box platform as quickly as possible.
Although Box provides many authentication methods, a recent incident with free developer accounts forced Box to limit the options for new free developer accounts.
So I’ve decide to create a Python template application with built in OAuth 2.0, ready to go, allowing you to immediately start sending requests to the API.
Create a free Box individual account
Navigate to the personal sign up page, fill in your information, and submit.
No credit card required…
Box registration page for free individual accounts
Complete the registration process, verifying your email.
Tip: If you have a gmail.com account and don’t want to create a brand new account just for this, you can use something like your.normal.email+box@gmail.com.
You can also use this to create multiple free accounts on box under the same email, and still be able to distinguish them.
Once you’re logged in you should see something like:
First log in at Box.com
At this point you don’t see the developer console menu entry yet.
Creating your first Box app
Navigate to the developer console, using this link: Box | Login
Box developer console with no apps
Create a new app and select custom app:
New application initial options
Fill in the information about your app and press next:
Select “User authentication (OAuth 2.0)”, and click create app:
Under the configuration tab scroll down to the “Redirect URI” section and enter a URL that your browser will redirect to after the user authorization process. For this application the default is http://127.0.0.1:500/callback but you can customize it to fit your needs.
Setting the redirect URI
Still under the configuration tab scroll down and select the application scopes you’re interested or just select all of them, and then press save changes:
Selecting application scopes
If you go back to “My Account” you’ll see that there is a new menu entry enabled for you to access the developer console:
Box free account upgraded to free developer account
You’re done! We will need to go back to the developer console to get the client id and some more information, so keep this open.
Using the Python template OAuth 2.0 application
This sample application will get you started faster, and allow you to create a simple Python script, a Flask, a FastAPI or anything else.
It includes the basics for an OAuth authentication flow, opening a web browser for the user authorization, and then listening for a single HTTP request to complete the authorization process.
It will store both the authorization and refresh tokens in a file on the local disk, unencrypted, so be aware.
The authorization token in valid for 60 minutes and will be automatically refreshed.
The refresh token is valid for 60 days, and unless the it is expired, the app wont ask the user to re-authorize the application with Box.
If you get stuck, just delete the token file and start over.
Why aren’t we using developer tokens?
In the configuration details of you app, you can activate a developer token, and just use it.
However this turns out to be not so practical for long coding sessions, since the developer tokens only last for 60 minutes. At that point developers often forget to explicitly refresh them in the developer console, before starting to get errors on the API. Use what you feel more comfortable with.
Why aren’t we using server side authentication?
Box platform does support client credential grants (CCG) and json web token (JWT) for server side authentication.
However at the moment (May 2023) Box temporarily disabled this for new free developer accounts. For more details read this note.
If you have an older developer account and access to the admin console, or if you are working with a corporate account, you are not affected, and can use any type of authentication you like.
Setting up the Python template application
The application can be found on this GitHub repository.
Once you cloned the repo or created a new one follow the instructions in setting up your python environment.
You’ll also need to copy the .env.sample file to .env and populate it with information from your application configuration.
CLIENT_ID = YOUR_CLIENT_ID
CLIENT_SECRET = YOU_CLIENT_SECRET
CALLBACK_HOSTNAME = 127.0.0.1
CALLBACK_PORT = 5000
REDIRECT_URI = http://127.0.0.1:5000/callback
You can customize the callback hostname, port and redirect URI, but they must be consistent with the configurations entered on the developer console.
You can run a quick test.
The first time the app runs it will open a browser and ask for the user to authorize the application in Box.
It will then log the current user details and list the contents of the root folder.
From this point on and as long as the refresh token has not expired, it will not ask the user again.
See the app working:
Have fun with the Box platform SDK.