The Base URL of the Rest API is:
https://api.real-debrid.com/rest/1.0/
Disable current access token, returns 204 HTTP code
None
HTTP Status Code | Reason |
---|---|
401 | Bad token (expired, invalid) |
Get server time, raw data returned. This request is not requiring authentication.
Y-m-d H:i:s
Get server time in ISO, raw data returned. This request is not requiring authentication.
Y-m-dTH:i:sO
Returns some informations on the current user.
User show schema
HTTP Status Code | Reason |
---|---|
401 | Bad token (expired, invalid) |
403 | Permission denied (account locked) |
Check if a file is downloadable on the concerned hoster. This request is not requiring authentication.
Name | Type | Description | |
---|---|---|---|
POST | link * | string | The original hoster link |
POST | password | string | Password to unlock the file access hoster side |
HTTP Status Code | Reason |
---|---|
503 | File unavailable |
Unrestrict a hoster link and get a new unrestricted link
Name | Type | Description | |
---|---|---|---|
POST | link * | string | The original hoster link |
POST | password | string | Password to unlock the file access hoster side |
POST | remote | int | 0 or 1, use Remote traffic, dedicated servers and account sharing protections lifted |
HTTP Status Code | Reason |
---|---|
401 | Bad token (expired, invalid) |
403 | Permission denied (account locked) |
Unrestrict a hoster folder link and get individual links, returns an empty array if no links found.
Name | Type | Description | |
---|---|---|---|
POST | link * | string | The hoster folder link |
HTTP Status Code | Reason |
---|---|
401 | Bad token (expired, invalid) |
403 | Permission denied (account locked) |
HTTP Status Code | Reason |
---|---|
400 | Bad Request (see error message) |
401 | Bad token (expired, invalid) |
403 | Permission denied (account locked, not premium) |
503 | Service unavailable (see error message) |
Name | Type | Description | |
---|---|---|---|
POST | link * | string | HTTP Link of the container file |
HTTP Status Code | Reason |
---|---|
400 | Bad Request (see error message) |
401 | Bad token (expired, invalid) |
403 | Permission denied (account locked, not premium) |
503 | Service unavailable (see error message) |
Get traffic informations for limited hosters (limits, current usage, extra packages)
HTTP Status Code | Reason |
---|---|
401 | Bad token (expired, invalid) |
403 | Permission denied (account locked) |
Get traffic details on each hoster used during a defined period
Name | Type | Description | |
---|---|---|---|
GET | start | date (YYYY-MM-DD) | Start period, default: a week ago |
GET | end | date (YYYY-MM-DD) | End period, default: today |
Warning: The period can not exceed 31 days.
HTTP Status Code | Reason |
---|---|
401 | Bad token (expired, invalid) |
403 | Permission denied (account locked) |
Get transcoding links for given file, {id} from /downloads or /unrestrict/link
HTTP Status Code | Reason |
---|---|
401 | Bad token (expired, invalid) |
403 | Permission denied (account locked) |
Get detailled media informations for given file, {id} from /downloads or /unrestrict/link
HTTP Status Code | Reason |
---|---|
401 | Bad token (expired, invalid) |
403 | Permission denied (account locked) |
503 | Service unavailable (problem finding metadata of the media) |
Get user downloads list
Name | Type | Description | |
---|---|---|---|
GET | offset | int | Starting offset (must be within 0 and X-Total-Count HTTP header) |
GET | page | int | Pagination system |
GET | limit | int | Entries returned per page / request (must be within 0 and 5000, default: 100) |
Warning: You can not use both offset and page at the same time, page is prioritzed in case it happens.
HTTP Status Code | Reason |
---|---|
401 | Bad token (expired, invalid) |
403 | Permission denied (account locked) |
Delete a link from downloads list, returns 204 HTTP code
None
HTTP Status Code | Reason |
---|---|
401 | Bad token (expired, invalid) |
403 | Permission denied (account locked) |
404 | Unknown Ressource |
Get user torrents list
Name | Type | Description | |
---|---|---|---|
GET | offset | int | Starting offset (must be within 0 and X-Total-Count HTTP header) |
GET | page | int | Pagination system |
GET | limit | int | Entries returned per page / request (must be within 0 and 5000, default: 100) |
GET | filter | string | "active", list active torrents only |
Warning: You can not use both offset and page at the same time, page is prioritzed in case it happens.
HTTP Status Code | Reason |
---|---|
401 | Bad token (expired, invalid) |
403 | Permission denied (account locked) |
Get all informations on the asked torrent
HTTP Status Code | Reason |
---|---|
401 | Bad token (expired, invalid) |
403 | Permission denied (account locked) |
Get list of instantly available file IDs by hoster, {hash} is the SHA1 of the torrent. You can test multiple hashes adding multiple /{hash} at the end of the request
HTTP Status Code | Reason |
---|---|
401 | Bad token (expired, invalid) |
403 | Permission denied (account locked, not premium) |
Get currently active torrents number and the current maximum limit
HTTP Status Code | Reason |
---|---|
401 | Bad token (expired, invalid) |
403 | Permission denied (account locked) |
Get available hosts to upload the torrent to.
HTTP Status Code | Reason |
---|---|
401 | Bad token (expired, invalid) |
403 | Permission denied (account locked) |
Name | Type | Description | |
---|---|---|---|
GET | host | string | Hoster domain (retrieved from /torrents/availableHosts) |
HTTP Status Code | Reason |
---|---|
400 | Bad Request (see error message) |
401 | Bad token (expired, invalid) |
403 | Permission denied (account locked, not premium) |
503 | Service unavailable (see error message) |
Name | Type | Description | |
---|---|---|---|
POST | magnet * | string | Magnet link |
POST | host | string | Hoster domain (retrieved from /torrents/availableHosts) |
HTTP Status Code | Reason |
---|---|
400 | Bad Request (see error message) |
401 | Bad token (expired, invalid) |
403 | Permission denied (account locked, not premium) |
503 | Service unavailable (see error message) |
Name | Type | Description | |
---|---|---|---|
POST | files * | string | Selected files IDs (comma separated) or "all" |
Warning: To get file IDs, use /torrents/info/{id}
None
HTTP Status Code | Reason |
---|---|
202 | Action already done |
400 | Bad Request (see error message) |
401 | Bad token (expired, invalid) |
403 | Permission denied (account locked, not premium) |
404 | Wrong parameter (invalid file id(s)) / Unknown ressource (invalid id) |
Delete a torrent from torrents list, returns 204 HTTP code
None
HTTP Status Code | Reason |
---|---|
401 | Bad token (expired, invalid) |
403 | Permission denied (account locked) |
404 | Unknown Ressource |
Get supported hosts. This request is not requiring authentication.
Get status of supported hosters or not and their status on competitors.
Get all supported links Regex, useful to find supported links inside a document. This request is not requiring authentication.
Get all supported folder Regex, useful to find supported links inside a document. This request is not requiring authentication.
Get all hoster domains supported on the service. This request is not requiring authentication.
Get current user settings with possible values to update.
HTTP Status Code | Reason |
---|---|
401 | Bad token (expired, invalid) |
403 | Permission denied (account locked) |
Name | Type | Description | |
---|---|---|---|
POST | setting_name * | string | "download_port", "locale", "streaming_language_preference", "streaming_quality", "mobile_streaming_quality", "streaming_cast_audio_preference" |
POST | setting_value * | string | Possible values are available in /settings |
None
HTTP Status Code | Reason |
---|---|
400 | Bad request (bad setting value or setting name) |
401 | Bad token (expired, invalid) |
403 | Permission denied (account locked) |
None
HTTP Status Code | Reason |
---|---|
401 | Bad token (expired, invalid) |
403 | Permission denied (account locked) |
503 | Service unavailable (not enough points) |
None
HTTP Status Code | Reason |
---|---|
401 | Bad token (expired, invalid) |
403 | Permission denied (account locked) |
None
HTTP Status Code | Reason |
---|---|
400 | Bad Request (see error message) |
401 | Bad token (expired, invalid) |
403 | Permission denied (account locked) |
Reset user avatar image to default, returns 204 HTTP code
None
HTTP Status Code | Reason |
---|---|
401 | Bad token (expired, invalid) |
403 | Permission denied (account locked) |
{
"id": int,
"username": "string",
"email": "string",
"points": int, // Fidelity points
"locale": "string", // User language
"avatar": "string", // URL
"type": "string", // "premium" or "free"
"premium": int, // seconds left as a Premium user
"expiration": "string" // jsonDate
}
{
"id": "string",
"filename": "string",
"mimeType": "string", // Mime Type of the file, guessed by the file extension
"filesize": int, // Filesize in bytes, 0 if unknown
"link": "string", // Original link
"host": "string", // Host main domain
"chunks": int, // Max Chunks allowed
"crc": int, // Disable / enable CRC check
"download": "string", // Generated link
"streamable": int // Is the file streamable on website
}
{
"id": "string",
"filename": "string",
"filesize": int, // Filesize in bytes, 0 if unknown
"link": "string", // Original link
"host": "string", // Host main domain
"chunks": int, // Max Chunks allowed
"crc": int, // Disable / enable CRC check
"download": "string", // Generated link
"streamable": int, // Is the file streamable on website
"type": "string", // Type of the file (in general, its quality)
"alternative": [
{
"id": "string",
"filename": "string",
"download": "string",
"type": "string"
},
{
"id": "string",
"filename": "string",
"download": "string",
"type": "string"
}
]
}
[
{
"id": "string",
"filename": "string",
"mimeType": "string", // Mime Type of the file, guessed by the file extension
"filesize": int, // bytes, 0 if unknown
"link": "string", // Original link
"host": "string", // Host main domain
"chunks": int, // Max Chunks allowed
"download": "string", // Generated link
"generated": "string" // jsonDate
},
{
"id": "string",
"filename": "string",
"mimeType": "string",
"filesize": int,
"link": "string",
"host": "string",
"chunks": int,
"download": "string",
"generated": "string",
"type": "string" // Type of the file (in general, its quality)
}
]
{
"string": { // Host main domain
"left": int, // Available bytes / links to use
"bytes": int, // Bytes downloaded
"links": int, // Links unrestricted
"limit": int,
"type": "string", // "links", "gigabytes", "bytes"
"extra": int, // Additional traffic / links the user may have buy
"reset": "string" // "daily", "weekly" or "monthly"
},
"string": {
"left": int,
"bytes": int,
"links": int,
"limit": int,
"type": "string",
"extra": int,
"reset": "string"
}
}
{
"YYYY-MM-DD": {
"host": { // By Host main domain
"string": int, // bytes downloaded on concerned host
"string": int,
"string": int,
"string": int,
"string": int,
"string": int
},
"bytes": int // Total downloaded (in bytes) this day
},
"YYYY-MM-DD": {
"host": {
"string": int,
"string": int,
"string": int,
"string": int,
"string": int,
},
"bytes": int
}
}
[
{
"id": "string",
"filename": "string",
"hash": "string", // SHA1 Hash of the torrent
"bytes": int, // Size of selected files only
"host": "string", // Host main domain
"split": int, // Split size of links
"progress": int, // Possible values: 0 to 100
"status": "downloaded", // Current status of the torrent: magnet_error, magnet_conversion, waiting_files_selection, queued, downloading, downloaded, error, virus, compressing, uploading, dead
"added": "string", // jsonDate
"links": [
"string" // Host URL
],
"ended": "string", // !! Only present when finished, jsonDate
"speed": int, // !! Only present in "downloading", "compressing", "uploading" status
"seeders": int // !! Only present in "downloading", "magnet_conversion" status
},
{
"id": "string",
"filename": "string",
"hash": "string",
"bytes": int,
"host": "string",
"split": int,
"progress": int,
"status": "downloaded",
"added": "string",
"links": [
"string",
"string"
],
"ended": "string"
},
]
[
{
"id": "string",
"filename": "string",
"original_filename": "string", // Original name of the torrent
"hash": "string", // SHA1 Hash of the torrent
"bytes": int, // Size of selected files only
"original_bytes": int, // Total size of the torrent
"host": "string", // Host main domain
"split": int, // Split size of links
"progress": int, // Possible values: 0 to 100
"status": "downloaded", // Current status of the torrent: magnet_error, magnet_conversion, waiting_files_selection, queued, downloading, downloaded, error, virus, compressing, uploading, dead
"added": "string", // jsonDate
"files": [
{
"id": int,
"path": "string", // Path to the file inside the torrent, starting with "/"
"bytes": int,
"selected": int // 0 or 1
},
{
"id": int,
"path": "string", // Path to the file inside the torrent, starting with "/"
"bytes": int,
"selected": int // 0 or 1
}
],
"links": [
"string" // Host URL
],
"ended": "string", // !! Only present when finished, jsonDate
"speed": int, // !! Only present in "downloading", "compressing", "uploading" status
"seeders": int // !! Only present in "downloading", "magnet_conversion" status
}
]
{
"id": "string",
"uri": "string" // URL of the created ressource
}
{
"id": "string",
"uri": "string" // URL of the created ressource
}
[
{
"host": "string", // Host main domain
"max_file_size": int // Max split size possible
},
{
"host": "string", // Host main domain
"max_file_size": int // Max split size possible
}
]
{
"string": { // First hash
"string": [ // hoster, ex: "rd"
// All file IDs variants
{
"int": { // file ID, you must ask all file IDs from this array on /selectFiles to get instant downloading
"filename": "string",
"filesize": int
},
"int": { // file ID
"filename": "string",
"filesize": int
}
},
{
"int": { // file ID
"filename": "string",
"filesize": int
}
}
]
},
"string": { // Second hash
"string": [ // hoster, ex: "rd"
// All file IDs variants
{
"int": { // file ID, you must ask all file IDs from this array on /selectFiles to get instant downloading
"filename": "string",
"filesize": int
},
"int": { // file ID
"filename": "string",
"filesize": int
}
},
{
"int": { // file ID
"filename": "string",
"filesize": int
}
}
]
}
}
{
"nb": int, // Number of currently active torrents
"limit": int // Maximum number of active torrents you can have
}
[
"string", // URL
"string",
"string"
]
[
"string", // URL
"string",
"string"
]
[
"string", // Domain
"string",
"string"
]
[
"string", // RegExp
"string",
"string"
]
{
"string": { // Host main domain
"id": "string",
"name": "string",
"image": "string" // URL
},
"string": {
"id": "string",
"name": "string",
"image": "string"
}
}
{
"string": { // Host main domain
"id": "string",
"name": "string",
"image": "string", // URL
"supported": int, // 0 or 1
"status": "string", // "up" / "down" / "unsupported"
"check_time": "string", // jsonDate
"competitors_status": {
"string": { // Competitor domain
"status": "string", // "up" / "down" / "unsupported"
"check_time": "string" // jsonDate
},
"string": {
"status": "string",
"check_time": "string"
},
"string": {
"status": "string",
"check_time": "string"
}
}
},
"string": {
"id": "string",
"name": "string",
"image": "string",
"supported": int,
"status": "string",
"check_time": "string",
"competitors_status": {
"string": {
"status": "string",
"check_time": "string"
},
"string": {
"status": "string",
"check_time": "string"
},
"string": {
"status": "string",
"check_time": "string"
}
}
}
}
{
"string": [ // Category name
{
"id": int, // Forum ID
"name": "string", // Forum name
"description": "string", // Forum description
"topics": int, // Number of topics inside the concerned forum
"posts": int, // Number of posts inside the concerned forum
"unread_content": int, // 0 or 1
"last_post": { // Last post details
"id": int,
"topic_id": int,
"user_id": int,
"user_name": "string",
"user_level": "string", // "user", "banned", "moderator", "administrator"
"date": "string" // jsonDate
}
},
{
"id": int,
"name": "string",
"description": "string",
"topics": int,
"posts": int,
"unread_content": int,
"last_post": {
"id": int,
"topic_id": int,
"user_id": int,
"user_name": "string",
"user_level": "string",
"date": "string"
}
}
],
"string": [
{
"id": int,
"name": "string",
"description": "string",
"topics": int,
"posts": int,
"unread_content": int,
"last_post": {
"id": int,
"topic_id": int,
"user_id": int,
"user_name": "string",
"user_level": "string",
"date": "string"
}
},
{
"id": int,
"name": "string",
"description": "string",
"topics": int,
"posts": int,
"unread_content": int,
"last_post": {
"id": int,
"topic_id": int,
"user_id": int,
"user_name": "string",
"user_level": "string",
"date": "string"
}
}
]
}
{
"host": "string", // Host main domain
"link": "string",
"filename": "string",
"filesize": int,
"supported": int
}
{
"apple": { // M3U8 Live Streaming format
"quality": "string",
"quality": "string"
},
"dash": { // MPD Live Streaming format
"quality": "string",
"quality": "string"
},
"liveMP4": { // Live MP4
"quality": "string",
"quality": "string"
},
"h264WebM": { // Live H264 WebM
"quality": "string",
"quality": "string"
}
}
{
"filename": "string", // Cleaned filename
"hoster": "string", // File hosted on
"link": "string", // Original content link
"type": "string", // "movie" / "show" / "audio"
"season": "string", // if found, else null
"episode": "string", // if found, else null
"year": "string", // if found, else null
"duration": float, // media duration in seconds
"bitrate": int, // birate of the media file
"size": int, // original filesize in bytes
"details": {
"video": {
"und1": { // if available, lang in iso_639 followed by a number ID
"stream": "string",
"lang": "string", // Language in plain text (ex "English", "French")
"lang_iso": "string", // Language in iso_639 (ex fre, eng)
"codec": "string", // Codec of the video (ex "h264", "divx")
"colorspace": "string", // Colorspace of the video (ex "yuv420p")
"width": int, // Width of the video (ex 1980)
"height": int // Height of the video (ex 1080)
}
},
"audio": {
"und1": { // if available, lang in iso_639 followed by a number ID
"stream": "string",
"lang": "string", // Language in plain text (ex "English", "French")
"lang_iso": "string", // Language in iso_639 (ex fre, eng)
"codec": "string", // Codec of the audio (ex "aac", "mp3")
"sampling": int, // Audio sampling rate
"channels": float // Number of channels (ex 2, 5.1, 7.1)
}
},
"subtitles": [
"und1": { // if available, lang in iso_639 followed by a number ID
"stream": "string",
"lang": "string", // Language in plain text (ex English, French)
"lang_iso": "string", // Language in iso_639 (ex fre, eng)
"type": "string" // Format of subtitles (ex "ASS" / "SRT")
}
]
},
"poster_path": "string", // URL of the poster image if found / available
"audio_image": "string", // URL of the music image in HD if found / available
"backdrop_path": "string" // URL of the backdrop image if found / available
}
{
"download_ports": [ // Possible "download_port" value to update settings
"string",
"string"
],
"download_port": "string", // Current user download port
"locales": { // Possible "locale" value to update settings
"string": "string",
"string": "string"
},
"locale": "string", // Current user locale
"streaming_qualities": [ // Possible "streaming_quality" value to update settings
"string",
"string",
"string",
"string"
],
"streaming_quality": "string", // Current user streaming quality
"mobile_streaming_quality": "string", // Current user streaming quality on mobile devices
"streaming_languages": { // Possible "streaming_language_preference" value to update settings
"string": "string",
"string": "string"
},
"streaming_language_preference": "string", // Current user streaming language preference
"streaming_cast_audio": [ // Possible "streaming_cast_audio_preference" value to update settings
"string",
"string"
],
"streaming_cast_audio_preference": "string" // Current user audio preference on Google Cast devices
}
{
"meta": {
"id": int,
"name": "string",
"description": "string",
"topics": int,
"autorisation_topic": int, // User allowed to make a new topic: 0 or 1
"autorisation_post": int, // User allowed to post in a topic: 0 or 1
"autorisation_stick": int, // User allowed to stick a topic: 0 or 1
"autorisation_moderation": int, // User allowed to use moderation tools: 0 or 1
},
"topics": {
"string": [ // "normal" or "sticky"
{
"id": int,
"title": "string",
"author": {
"user_id": int,
"username": "string",
"level": "string"
},
"posts": int,
"views": int,
"unread_content": int,
"last_post": {
"id": int,
"user_id": int,
"user_name": "string",
"user_level": "string",
"date": "string"
}
},
{
"id": int,
"title": "string",
"author_user_id": int,
"author_user_name": "string",
"posts": int,
"views": int,
"unread_content": int,
"last_post": {
"id": int,
"user_id": int,
"user_name": "string",
"user_level": "string",
"date": "string"
}
}
]
}
}
Here are some example calls, using cURL:
curl -X GET \ -H "Authorization: Bearer your_api_token" \ "https://api.real-debrid.com/rest/1.0/user"
HTTP/1.1 200 OK
Content-Type: application/json
etag: fd6e5a758cf66fe4e92bc2bc7061d9f32dc542af
date: Fri, 12 Jul 2013 12:12:12 GMT
{
"id": 42,
"username": "administrator",
"email": "support@real-debrid.com",
"points": 12347428,
"avatar": "https:\/\/s.real-debrid.com\/images\/avatars\/42424242424.png",
"type": "premium",
"premium": 666666,
"expiration": "2032-06-06T04:42:42.000Z"
}
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.
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.
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.
The Base URL of the OAuth2 API is:
https://api.real-debrid.com/oauth/v2/
This authentication process uses three-legged OAuth2.
The following URLs are used in this process:
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…).
Your application redirects the user to Online.net's authorize endpoint, with the following query string parameters:
client_id
: your app's client_idredirect_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 CSRFhttps://api.real-debrid.com/oauth/v2/auth?client_id=ABCDEFGHIJKLM&redirect_uri=https%3A%2F%2Fexample.com&response_type=code&state=iloverd
The user chooses to authorize your application.
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 tokenstate
: the same value that you sent earlierUsing 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 earlierredirect_uri
: one of your application's redirect URLsgrant_type
: use the value "authorization_code"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"
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 secondstoken_type
: "Bearer"refresh_token
: token that only expires when your application rights are revoked by userYour 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.
This authentication process uses a variant of OAuth2, tailored for mobile devices.
The following URLs are used in this process:
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.
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.
https://api.real-debrid.com/oauth/v2/device/code?client_id=ABCDEFGHIJKLM
{
"device_code": "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789",
"user_code": "ABCDEF0123456",
"interval": 5,
"expires_in": 1800,
"verification_url": "https:\/\/real-debrid.com\/device"
}
Your application asks the user to go to the verification endpoint (provided by verification_url) and to type the code provided by user_code.
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""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.
The user enters the code, and then logs in if they aren't logged in yet.
The user chooses to authorize your application, and can then close the browser window.
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 secondstoken_type
: "Bearer"refresh_token
: token that only expires when your application rights are revoked by userYour 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.
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:
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.
https://api.real-debrid.com/oauth/v2/device/code?client_id=ABCDEFGHIJKLM&new_credentials=yes
{
"device_code": "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789",
"user_code": "ABCDEF0123456",
"interval": 5,
"expires_in": 1800,
"verification_url": "https:\/\/real-debrid.com\/device"
}
Your application asks the user to go to the verification endpoint (provided by verification_url) and to type the code provided by user_code.
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.
The user enters the code, and then logs in if they aren't logged in yet.
The user chooses to authorize your application, and can then close the browser window.
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 userclient_secret
Your application stores these values and will use them for later requests.
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 endpointclient_secret
: the value of client_secret
provided by the call to the credentials endpointcode
: 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 secondstoken_type
: "Bearer"refresh_token
: token that only expires when your application rights are revoked by usercurl -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 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.
Warning: This workflow requires a special authorization on your client_id from the webmaster.
The following URLs are used in this process:
Your application makes a direct POST request to the token endpoint, with the following parameters:
client_id
username
: User loginpassword
: User passwordgrant_type
: use the value "password"For testing purposes only, you can force the server to give you the two factor error by sending:
force_twofactor
: trueThis 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
: 11Open 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 earliergrant_type
: use the value "twofactor"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.
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 earliergrant_type
: use the value "twofactor"send
: trueOn 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 earliergrant_type
: use the value "twofactor"response
: use the value the user inputsOn 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 secondstoken_type
: "Bearer"refresh_token
Important: You must NOT save any login details, only keep refresh_token as the « password ».
curl -X POST "https://api.real-debrid.com/oauth/v2/token" -d "client_id=ABCDEFGHIJKLM&username=abcdefghsecret0123456789&password=abcdefghsecret0123456789&grant_type=password"
The following URLs are used in this process:
Using the value of refresh_token your application saved earlier, your application makes a direct POST request to the token endpoint, with the following parameters:
client_id
client_secret
code
: the value of refresh_token
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 secondstoken_type
: "Bearer"refresh_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"
In addition to the HTTP error code, errors come with a message (error parameter) and a numeric code (error_code parameter). The error message is meant to be human-readable, while the numeric codes should be used by your application.
-1 | Internal error |
---|---|
1 | Missing parameter |
2 | Bad parameter value |
3 | Unknown method |
4 | Method not allowed |
5 | Slow down |
6 | Ressource unreachable |
7 | Resource not found |
8 | Bad token |
9 | Permission denied |
10 | Two-Factor authentication needed |
11 | Two-Factor authentication pending |
12 | Invalid login |
13 | Invalid password |
14 | Account locked |
15 | Account not activated |
16 | Unsupported hoster |
17 | Hoster in maintenance |
18 | Hoster limit reached |
19 | Hoster temporarily unavailable |
20 | Hoster not available for free users |
21 | Too many active downloads |
22 | IP Address not allowed |
23 | Traffic exhausted |
24 | File unavailable |
25 | Service unavailable |
26 | Upload too big |
27 | Upload error |
28 | File not allowed |
29 | Torrent too big |
30 | Torrent file invalid |
31 | Action already done |
32 | Image resolution error |
33 | Torrent already active |
34 | Too many requests |
35 | Infringing file |
36 | Fair Usage Limit |