Real-Debrid API Documentation

Authentication

Calls that require authentication expect an HTTP header Authorization bearing a token, using the following format:

Authorization: Bearer your_api_token

If you can not send an Authorization HTTP header you can also send your token as a parameter in REST API URLs, the parameter is called auth_token:

/rest/1.0/method?auth_token=your_api_token

This token can either be your private API token, or a token obtained using OAuth2's three-legged authentication.

Warning: Never ever use your private API token for public applications, it is insecure and gives access to all methods.

Authentication for applications

First, you must create an app in your control panel.

Once you have created an app, you are provided a client_id and client_secret that you will use for the authentication process.

Opensource Apps

You can use this client ID on opensource apps if you don't need custom scopes or name:

X245A4XAIBGVM

This app is allowed on following scopes: unrestrict, torrents, downloads, user

This client ID can have stricter limits than service limits due to poorly designed apps using it.

Which authentication process should you use?

• If your application is a website: three-legged OAuth2.
• If your application is a mobile app: OAuth2 for devices.
• If your application is an opensource app or a script: OAuth2 for opensource apps.

The Base URL of the OAuth2 API is:

https://api.real-debrid.com/oauth/v2/

Workflow for websites or client applications

This authentication process uses three-legged OAuth2.

The following URLs are used in this process:

• authorize endpoint: /auth
• token endpoint: /token

Note: if your application is not a website, you will have to make the user do these steps in a web view (e.g. UIWebView on iOS, WebView on Android…).

Full workflow

1. Your application redirects the user to Online.net's authorize endpoint, with the following query string parameters:

   • client_id: your app's client_id
   • redirect_uri: one of your application's redirect URLs (must be url encoded)
   • response_type: use the value "code"
   • state: an arbitrary string that will be returned to your application, to help you check against CSRF

   Example URL for authorization:

   https://api.real-debrid.com/oauth/v2/auth?client_id=ABCDEFGHIJKLM&redirect_uri=https%3A%2F%2Fexample.com&response_type=code&state=iloverd

2. The user chooses to authorize your application.

3. The user gets redirected to the URL you specified using the parameter redirect_uri, with the following query string parameters:

   • code: the code that you will use to get a token
   • state: the same value that you sent earlier

4. Using the value of code, your application makes a direct POST request (not in the user's browser) to the token endpoint, with the following parameters:

   • client_id
   • client_secret
   • code: the value that you received earlier
   • redirect_uri: one of your application's redirect URLs
   • grant_type: use the value "authorization_code"

   Example cURL call to obtain an access token:

   curl -X POST "https://api.real-debrid.com/oauth/v2/token" -d "client_id=ABCDEFGHIJKLM&client_secret=abcdefghsecret0123456789&code=ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789&redirect_uri=https://your-app.tld/realdebrid_api&grant_type=authorization_code"

5. If everything is correct, the access token is returned as a JSON object with the following properties:

   • access_token
   • expires_in: token validity period, in seconds
   • token_type: "Bearer"
   • refresh_token: token that only expires when your application rights are revoked by user

6. Your application stores the access token and uses it for the user's subsequent visits.

   Your application must also stores the refresh token that will be used to get new access tokens once their validity period is expired.

Workflow for mobile apps

This authentication process uses a variant of OAuth2, tailored for mobile devices.

The following URLs are used in this process:

• device endpoint: /device/code
• token endpoint: /token

Note: you may have to make the user do some steps in a web view (e.g. UIWebView on iOS, WebView on Android…) if you want to do all these steps from the mobile app.

Full workflow

1. Your application makes a direct request to the device endpoint, with the query string parameter client_id, and obtains a JSON object with authentication data that will be used for the rest of the process.

   Example URL to obtain authentication data:

   https://api.real-debrid.com/oauth/v2/device/code?client_id=ABCDEFGHIJKLM

   Example authentication data:

   {
       "device_code": "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789",
       "user_code": "ABCDEF0123456",
       "interval": 5,
       "expires_in": 1800,
       "verification_url": "https:\/\/real-debrid.com\/device"
   }
   

2. Your application asks the user to go to the verification endpoint (provided by verification_url) and to type the code provided by user_code.

3. Using the value of device_code, every 5 seconds your application starts making direct POST requests to the token endpoint, with the following parameters:

   • client_id
   • client_secret
   • code: the value of device_code
   • grant_type: use the value "http://oauth.net/grant_type/device/1.0""

   Example cURL call to obtain an access token:

   curl -X POST "https://api.real-debrid.com/oauth/v2/token" -d "client_id=ABCDEFGHIJKLM&client_secret=abcdefghsecret0123456789&code=ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789&grant_type=http://oauth.net/grant_type/device/1.0"

   Your application will receive an error message until the user has entered the code and authorized the application.

4. The user enters the code, and then logs in if they aren't logged in yet.

5. The user chooses to authorize your application, and can then close the browser window.

6. Your application's call to the token endpoint now returns the access token as a JSON object with the following properties:

   • access_token
   • expires_in: token validity period, in seconds
   • token_type: "Bearer"
   • refresh_token: token that only expires when your application rights are revoked by user

7. Your application stores the access token and uses it for the user's subsequent visits.

   Your application must also stores the refresh token that will be used to get new access tokens once their validity period is expired.

Workflow for opensource apps

This authentication process is similar to OAuth2 for mobile devices, with the difference that opensource apps or scripts can not be shipped with a client_secret (since it's meant to remain secret).

The principle here is to get a new set of client_id and client_secret that are bound to the user. You may reuse these credentials by using OAuth2 for mobile devices.

Warning: You should not redistribute the credentials. Usage with another account will display the UID of the user who obtained the credentials. E.g. instead of displaying "The most fabulous app" it will display "The most fabulous app (UID: 000)".

The following URLs are used in this process:

• device endpoint: /device/code
• credentials endpoint: /device/credentials
• token endpoint: /token

Full workflow

1. Your application makes a direct request to the device endpoint, with the query string parameters client_id and new_credentials=yes, and obtains a JSON object with authentication data that will be used for the rest of the process.

   Example URL to obtain authentication data:

   https://api.real-debrid.com/oauth/v2/device/code?client_id=ABCDEFGHIJKLM&new_credentials=yes

   Example authentication data:

   {
       "device_code": "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789",
       "user_code": "ABCDEF0123456",
       "interval": 5,
       "expires_in": 1800,
       "verification_url": "https:\/\/real-debrid.com\/device"
   }
   

2. Your application asks the user to go to the verification endpoint (provided by verification_url) and to type the code provided by user_code.

3. Using the value of device_code, every 5 seconds your application starts making direct requests to the credentials endpoint, with the following query string parameters:

   • client_id
   • code: the value of device_code

   Your application will receive an error message until the user has entered the code and authorized the application.

4. The user enters the code, and then logs in if they aren't logged in yet.

5. The user chooses to authorize your application, and can then close the browser window.

6. Your application's call to the credentials endpoint now returns a JSON object with the following properties:

   • client_id: a new client_id that is bound to the user
   • client_secret

   Your application stores these values and will use them for later requests.

7. Using the value of device_code, your application makes a direct POST request to the token endpoint, with the following parameters:

   • client_id: the value of client_id provided by the call to the credentials endpoint
   • client_secret: the value of client_secret provided by the call to the credentials endpoint
   • code: the value of device_code
   • grant_type: use the value "http://oauth.net/grant_type/device/1.0"

   The answer will be a JSON object with the following properties:

   • access_token
   • expires_in: token validity period, in seconds
   • token_type: "Bearer"
   • refresh_token: token that only expires when your application rights are revoked by user

   Example cURL call to obtain an access token:

   curl -X POST "https://api.real-debrid.com/oauth/v2/token" -d "client_id=ABCDEFGHIJKLM&client_secret=abcdefghsecret0123456789&code=ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789&grant_type=http://oauth.net/grant_type/device/1.0"

8. Your application stores the access token and uses it for the user's subsequent visits.

   Your application must also stores the refresh token that will be used to get new access tokens once their validity period is expired.

Workflow for old apps

Warning: This workflow requires a special authorization on your client_id from the webmaster.

The following URLs are used in this process:

• token endpoint: /token

Full workflow

1. Your application makes a direct POST request to the token endpoint, with the following parameters:

   • client_id
   • username: User login
   • password: User password
   • grant_type: use the value "password"

   ---

   Testing Two-Factor Process

   For testing purposes only, you can force the server to give you the two factor error by sending:

   • force_twofactor: true

   This will return the two factor validation URL:

   • verification_url: The URL you should redirect the user to.
   • twofactor_code
   • error: "twofactor_auth_needed"
   • error_code: 11

   Workflow if you use a WebView / Popup

   Open a WebView / Popup with the value of verification_url

   Using the value of twofactor_code, your application makes a direct POST request (not in the user's browser) to the token endpoint, with the following parameters:

   • client_id
   • code: the value that you received earlier
   • grant_type: use the value "twofactor"

   Example cURL call to obtain an access token:

   curl -X POST "https://api.real-debrid.com/oauth/v2/token" -d "client_id=ABCDEFGHIJKLM&code=ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789&grant_type=twofactor"

   You will get a 403 HTTP code until the user inputs the correct security code on verification_url.

   Workflow if you want to handle the security code validation process

   The SMS or email is not sent until you make a request to the token endpoint, with the following parameters:

   • client_id
   • code: the value that you received earlier
   • grant_type: use the value "twofactor"
   • send: true

   On success, you will get a 204 HTTP code, if the limit is reached then it will be a 403 HTTP code.

   To validate the security code the user gives you, make a request to the token endpoint, with the following parameters:

   • client_id
   • code: the value that you received earlier
   • grant_type: use the value "twofactor"
   • response: use the value the user inputs

   On error, you will get a 400 HTTP code, if the number of attempts is reached then you will get a 403 HTTP code.

   ---

   On success, the answer will be a JSON object with the following properties:

   • access_token
   • expires_in: token validity period, in seconds
   • token_type: "Bearer"
   • refresh_token

   Important: You must NOT save any login details, only keep refresh_token as the « password ».

   Example cURL call to obtain an access token:

   curl -X POST "https://api.real-debrid.com/oauth/v2/token" -d "client_id=ABCDEFGHIJKLM&username=abcdefghsecret0123456789&password=abcdefghsecret0123456789&grant_type=password"