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.
bitly currently supports the OAuth 2 draft specification. All OAuth2 requests MUST use the SSL
endpoint available at
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
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
Redirect the user to
https://bitly.com/oauth/authorize, using the
redirect_uriparameters 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
stateparameter which will be included unchanged in the redirect. An example redirect URL looks like:
Upon authorizing your application, the user is directed to the page specified in the
redirect_uriparameter. We append a
codeparameter 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
http://myexamplewebapp.com/oauth_page, a successful authentication will redirect the user to
http://myexamplewebapp.com/oauth_page?code=..... If the
stateparameter was included in the request, it will be added unchanged to the redirect URI, eg.
/oauth/access_tokenAPI endpoint documented below to acquire an OAuth access token, passing the
codevalue appended by bitly to the previous redirect and the same
redirect_urivalue 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
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.
There are two ways to convert a username and password directly into an access token:
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
is made to
grant_type set to
password, and the
Authorization header set with
NOTE: You should only make this call once and store the returned token securely. You should not make this call per shorten or at any other high-frequency interval. To protect our users' security, we aggressively rate limit calls to these endpoints.
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
Authorization: is set to
"Basic " + base64encode(client_id + ":" + client_secret). An example
response might look like:
Applications MUST NOT store the Bitly credentials locally.
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
username- the user's Bitly username.
password- the user's Bitly password.
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.
Specifically, applications using this flow should make the authentication call once and store the returned access token in a secure manner for use in all subsequent API calls. Frequent calls to this endpoint (e.g. making a call per-shorten) will result in your account getting rate limited.
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.
AuthorizationHeader with the value
"Basic " + base64encode(username + ":" + password)
client_id is not specified, an access token will be generated under a
bitly API application.
- This request MUST be a HTTP
- This endpoint is only available on
deprecated - ApiKey authentication is deprecated in favor of OAuth requests.
API requests to endpoints that accept a
apiKey may be made to
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.