Authentication

Most bitly API endpoints require an OAuth access token. If you only need a token for your own account and will not be authenticating any additional end-users, you can generate a developer access token from https://bitly.com/a/oauth_apps or by using the Basic Authentication Flow

OAuth

bitly currently supports the OAuth 2 draft specification. All OAuth2 requests MUST use the SSL endpoint available at https://api-ssl.bitly.com/

OAuth 2.0 is a simple and secure authentication mechanism. It allows applications to acquire an access token for bitly via a quick redirect to the bitly site. Once an application has an access token, it can access a user's link metrics, and shorten links using that user's bitly account. Authentication with OAuth can be accomplished in the following steps:

OAuth authentication is made by adding the access_token parameter with a user's access token. All requests with OAuth tokens must be made over SSL to https://api-ssl.bitly.com/.

access_token=**access_token**

OAuth Web Flow

Web applications can easily acquire an OAuth access token for a bitly end user by following these steps:

  • Register your application here -- your application will be assigned a client_id and a client_secret.

  • Redirect the user to https://bitly.com/oauth/authorize, using the client_id and redirect_uri parameters to pass your client ID and the page you would like to redirect to upon acquiring an access token. You can also pass an optional state parameter which will be included unchanged in the redirect. An example redirect URL looks like: https://bitly.com/oauth/authorize?client_id=...&state=...&redirect_uri=http://myexamplewebapp.com/oauth_page

  • Upon authorizing your application, the user is directed to the page specified in the redirect_uri parameter. We append a code parameter to this URI that 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=..... If the state parameter was included in the request, it will be added unchanged to the redirect URI, eg. http://myexamplewebapp.com/oauth_page?code=...&state=...

  • Use the /oauth/access_token API endpoint documented below to acquire an OAuth access token, passing the code value appended by bitly to the previous redirect and the same 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 utilize the bitly API on that user's behalf.

An example request might look like:

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 an example response:

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

access_token=TOKEN&login=BITLY_LOGIN&apiKey=BITLY_API_KEY

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 in the format of access_token=%s&login=%s&apiKey=%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 specified user.
  • login - the end-user's bitly username.
  • apiKey - deprecated this value will be removed in the future.

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

Bitly supports the Resource Owner Credential Grant flow of the OAuth2 specification to exchange a user's Bitly username and password for an access token. A POST request is made to /oauth/access_token with grant_type set to password, and the Authorization header set with the client_id and client_secret. 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). An example response might look like:

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 Credential 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 (e.g.: 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.

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)

If client_id is not specified, an access token will be generated under a bitly API application.

Note:

  • This request MUST be a HTTP POST request.
  • This endpoint is only available on https://api-ssl.bitly.com/.

ApiKey authentication

deprecated - ApiKey authentication is deprecated in favor of OAuth requests.

API requests to endpoints that accept a login and apiKey may be made to http://api.bitly.com/ or https://api-ssl.bitly.com/.

Note that, for some accounts created via Twitter or Facebook, the account login is different from the display name. To find your canonical account login, please visit http://bitly.com/a/your_api_key.

login=**login**&apiKey=**apiKey**