Rebrandly for Developers

Use our API to create, track and share custom short links that incorporate your brand domain name.

Get Started

OAuth flow

IMPORTANT: you don't need to implement an OAuth flow if you know the API key of the Rebrandly account. If you are using Rebrandly API with your own Rebrandly account, it's lot easier to use an API Key than to use an OAuth flow.

If you want to use the Rebrandly API in your app on behalf of a Rebrandly account, you need to authorize your application.
You can submit your authorization request at Rebrand.ly/AuthorizeMe.

📘

Redirect URIs

When you request Rebrandly to authorize your application for a OAuth 2.0 integration, you are supposed to provide Rebrandly with one or more URLs where you wish the sensitive authentication data to be delivered to.

When you authorize a new app in Rebrandly, a client_id is assigned to it.
That's enough to let your app users connect with their Rebrandly accounts:
if your users happen not to have a Rebrandly account, they will be able to register a new account from the same page and then get back to you.

You can either search for an OAuth client in your favorite programming language or you can configure your own HTTP calls.

If the following standard OAuth flow doesn't fit your needs, we can arrange together for another OAuth flow.

Using an OAuth client

There are plenty of OAuth clients you can include in your application to get the authorization job done for you.

Configuring a basic OAuth "code" flow

If you need to take control over the http flow, here's how to manually setup the authentication process.
In order to get a valid token, you have to redirect your users to https://oauth.rebrandly.com/connect/authorize with the following query parameters:

Parameter

Description

client_id

The unique Client ID associated with your app.

redirect_uri

This is the callback to your app you asked to be authorized in your request.

You can ask us to change it anytime.

response_type

Set this to be code.
(token mode is also supported, if you need)

scope

This should always be rbapi offline_access.

Mind that this value should be properly URL encoded, so that the full Key/Value parameter would be &scope=rbapi%20offline_access.

A full URL would be like: https://oauth.rebrandly.com/connect/authorize with parameters ?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&response_type=code&scope=rbapi%20offline_access.

Your users will be requested to compile the Rebrandly Signin/Signup form, and the Rebrandly authentication servers will send them back to your app via HTTP redirection (What if I need HTTP POST?) at the redirect_uri you provided in the request, with a code in URL, e.g.:

https://yourapp.com/#code=CODE&scope=rbapi%20offline_access

Now that you have received a CODE, you are supposed to exchange it for a valid authentication token. In order to exchange it, an additional API call should be performed from your app as follows:

HTTP POST
https://oauth.rebrandly.com/connect/token

with "Content-Type" header set to "application/x-www-form-urlencoded"

with the following HTTP Body parameters:

Parameter

Description

code

The code you received from the server on the first request

client_id

The unique Client ID associated with your app.

client_secret

The Client Secret associated with your app.

grant_type

Set this to be authorization_code.

redirect_uri

One of your Client App Redirect URIs.

Although no other redirect will be performed to this URL, this is still needed for a number of reasons, e.g. to double-check that your application is indeed the intended issuer for this request.

The HTTP Response will expose a JSON in the body as follows:

{
  "access_token": "YOUR_TOKEN",
  "expires_in": TTL,
  "token_type": "Bearer",
  "refresh_token": "YOUR_REFRESH_TOKEN"
}

where YOUR_TOKEN is a Bearer Token you can use to authenticate your requests (see next section), and YOUR_REFRESH_TOKEN is a code you can use to automatically gather a new valid token once the old token expires (it will expire after TTL seconds).

Refreshing an expired token

Authentication tokens eventually expire.

If your application needs Rebrandly users to stay logged in for a long time, you can persist on your system the refresh_token - which was provided along with the access token (please see previous section) - to extend the current Rebrandly authentication session (although using a different authentication token) with the following API call:

HTTP POST
​https://oauth.rebrandly.com/connect/token
with "Content-Type" header set to "application/x-www-form-urlencoded"

with the following HTTP Body parameters:

Parameter

Description

refresh_token

The refresh_token which was provided to you along with the original token.

client_id

The unique Client ID associated with your app.

client_secret

The Client Secret associated with your app.

grant_type

Set this to be refresh_token.

The HTTP Response will expose a JSON in the body as follows:

{
  "access_token": "YOUR_TOKEN",
  "expires_in": TTL,
  "token_type": "Bearer",
  "refresh_token": "YOUR_REFRESH_TOKEN"
}

where YOUR_TOKEN is a new Bearer token you can use to authenticate your requests (see next section), and YOUR_REFRESH_TOKEN is a code you can - again - use to automatically gather a new valid token once also this second token expires (it will expire after TTL seconds).

You can refresh tokens indefinitely over time as they expire.

Authenticating requests with OAuth

Now that you have a valid token, you need to add this HTTP header in all future API requests to https://api.rebrandly.com:

Header name

Header value

Authorization

"Bearer YOUR_TOKEN"
(Bearer - or in general your token type -, then a white space, then the token)

Yet another cURL example:

curl \
-H "Authorization: Bearer YOUR_TOKEN" \
'https://api.rebrandly.com/v1/account'

Updated 3 months ago


OAuth flow


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.