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 6 months ago