BitlyDeveloper
Start Now

Authentication

Generic access token

Generate your access token.

You will use this token in your request's Authorization header. Here is an example: Authorization: Bearer {token}

This will suffice for most use cases, such as connecting to a communication platform to distribute SMS messages and other point-to-point integrations.

OAuth 2.0

To perform actions on behalf of end-users, you’ll need to authenticate them via OAuth 2.0. When a shortened link is created it will be added to a user’s history, allowing them to manage and track their links in the Bitly apps.

OAuth web flow

To acquire an OAuth access token for a Bitly user through a web application:

  1. Log in to Bitly, go to Developer settings and click Register new app. You'll receive an email with a registration link. Complete the registration and your app will be assigned a client_id and a client_secret.

  2. Redirect the user to https://bitly.com/oauth/authorize. You will use the client_id parameter to pass your client ID, and the redirect_uri parameter to pass the page you would like to point to when acquiring an access token.

    You can also pass an optional state parameter which will be included unchanged in the redirect, such as: https://bitly.com/oauth/authorize?client_id=...&state=...&redirect_uri=http://myexamplewebapp.com/oauth_page.

  3. When your application is authorized, the user is directed to the page specified in the redirect_uri parameter. Bitly appends a code parameter to this URI. The parameter contains a value that can be exchanged for an OAuth access token using the oauth/access_token endpoint documented below.

    For example, if you passed a redirect_uri value of: http://myexamplewebapp.com/oauth_page A successful authentication will redirect the user to: http://myexamplewebapp.com/oauth_page?code=..... And if the state parameter is included in the request, it will be added unchanged to the redirect URI: http://myexamplewebapp.com/oauth_page?code=...&state=....

  4. Use the /oauth/access_token API endpoint documented below to acquire an OAuth access token. Pass the code value appended by Bitly to the previous redirect and the redirect_uri value that was used previously.

    This API endpoint will return an OAuth access token, as well as the specified Bitly user's login and API key, allowing your application to use the Bitly API on their behalf.

An example request:

POST /oauth/access_token HTTP/1.1
Host: api-ssl.bitly.com
Content-Type: application/x-www-form-urlencoded

client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&code=CODE&redirect_uri=REDIRECT_URI

And the example response:

HTTP/1.1 200 OK
Content-Type: application/x-www-form-urlencoded
Content-Length: 57

access_token=TOKEN&login=BITLY_LOGIN

Parameters for OAuth web flow

  • client_id - your application's Bitly client id.
  • client_secret - your application's Bitly client secret.
  • code - the OAuth verification code acquired via OAuth's web authentication protocol.
  • redirect_uri - the page to which a user was redirected upon successfully authenticating.
  • state - optional state to include in the redirect URI.
  • grant_type - optional, if present must be authorization_code.

Response value

By default, a URL encoded string is formatted as:
access_token=%s&login=%s

If you set the Accept request header to application/json, we'll return a JSON dictionary and appropriate Content-Type response header.

  • access_token - the OAuth access token for a specified user.
  • login - the user's Bitly username.

Exchanging a username and password for an access token

There are two ways to convert a username and password directly into an access token:

  • Resource Owner Credentials Grants
  • HTTP Basic Authentication

Resource owner credentials grants

To exchange a user's Bitly username and password for an access token, Bitly supports the Resource Owner Credentials Grant flow of the OAuth 2.0 specification.

A POST request is made to /oauth/access_token.

  • Set grant_type to password.
  • Set Authorization header to the client_id and client_secret.

You should only make this call once and store the returned token securely. Frequent calls to this endpoint, such as making a call every time you shorten a link, will result in your account getting rate limited. This is to maintain the security of your account.

For example:

POST /oauth/access_token HTTP/1.1
Host: api-ssl.bitly.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

grant_type=password&username=bitlyuser&password=bitlypassword

Where Authorization: is set to "Basic " + base64encode(client_id + ":" + client_secret).

And the example response:

HTTP/1.1 200 OK
Content-Type: text/javascript; charset=UTF-8
Content-Length: 60

{"access_token": "e663e30818201d28dd07803e57333bed4f15803a"}

Applications must not store the Bitly credentials locally.

You can use the following curl command to generate an access token for your own application (line breaks inserted for readability):

curl -u "CLIENT_ID:CLIENT_SECRET" -d "grant_type=password" -d "username=USERNAME" \
-d "password=PASSWORD" https://api-ssl.bitly.com/oauth/access_token

Parameters for resource owner credentials grant flow

grant_type - must be password username - the user's Bitly username password - the user's Bitly password

HTTP basic authentication flow

For some applications it's impractical to use a web flow for access tokens (for example, command line scripts). An OAuth access token can be acquired by making a single call to the /oauth/access_token API endpoint documented below. The easiest way to do so is by running the curl command, also documented below.

curl -u "username:password" -X POST "https://api-ssl.bitly.com/oauth/access_token"

Applications using OAuth Basic Authentication Flow:

  • Must not store Bitly end-user passwords.
  • Should make the authentication call only once and store the returned access token in a secure manner for use in all subsequent API calls.

Frequent calls to this endpoint, such as making a call every time you shorten a link, will result in your account getting rate limited. This is to maintain the security of your account.

An example request:

POST /oauth/access_token HTTP/1.1
Host: api-ssl.bitly.com
Authorization: Basic czZCaGRSa3F0MzpnWDF
Content-Type: application/x-www-form-urlencoded

client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET

And an example response:

HTTP/1.1 200 OK
Content-Type: text/plain
Content-Length: 40

e663e30818201d28dd07803e57333bed4f15803a

Parameters for HTTP basic authentication flow

  • client_id - (optional) your application's Bitly client id.
  • client_secret - (optional) your application's Bitly client secret.
  • Authorization header with the value "Basic " + base64encode(username + ":" + password)

A couple of important things to keep in mind:

Generating a token with two-factor authentication enabled

There are a few restrictions in place to be aware of if you are attempting to generate a token and you have 2FA (two-factor authentication) enabled on your account.

  1. You will not be able to generate an access token by using the HTTP basic authentication flow. You will need to utilize either Owner Credentials or OAuth authentication flows.

  2. If you are attempting to generate a token by exchanging a username and password, and you have 2-factor authentication (2FA) enabled, you will receive the error message "2FA_CODE_REQUESTED." Bitly will send the code to your mobile device via SMS, and you will need to make a subsequent, second request to /oauth/access_token with the code in an additional code parameter.