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. An example redirect URL looks like: https://bitly.com/oauth/authorize?client_id=...&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=....

  • 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.

OAuth 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.

Applications using OAuth Basic Authentication Flow SHOULD NOT store bitly end-user passwords.

/oauth/access_token

This endpoint is used to acquire an access_token..

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.

Parameters for OAuth 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.

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

Note:

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

Response Value

URL encoded string in the format of access_token=%s&login=%s&apiKey=%s

  • 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.

ApiKey authentication

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

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**

OAuth XAuth Flow

deprecated XAuth Flow has been deprecated in favor of the Basic Authentication Flow. The OAuth Basic Authentication flow allows you to authenticate end-users with their login and password, and is more secure than XAuth.

© 2013 bitlyTM
handmade in nyc