-
Notifications
You must be signed in to change notification settings - Fork 0
OAuth
Go to serble.net/oauthapps and click New App. Enter a name and description for it and then click Create.
This is how Serble will identify your app.
After clicking create you will be sent back to serble.net/oauthapps and in there should should be able to find your app's name,
below the name it should display information associated with the app. Look for ID and ClientSecret and make note of them.
Your app's scope determines what your app can access from a users account. It should be a list of scope IDs seperated by a space character
%20. Here is a list of scopes you can request:
full_access: This scope gives you full access over the user's account
file_host: Allows you to view the user's files that they uploaded to files.serble.net and upload/manage files
on their behalf
user_info: Allows you to view the account's information, for example their username email and plan
apps_control: Allows you to manage the user's authorised apps
When you want to gain access to a user's account, navigate them to
https://serble.net/oauth/authorize or https://api.serble.net/api/v1/oauth/auth and include the following query params:
redirect_uri: This should be the URI you want Serble to navigate the user to with the OAuth token
client_id: Your app's client ID that you should have from step 1
response_type: Set this to token
scope: The scope that the app requires
state: A string that you can set to help prevent any malicious attacks
The user will then be sent to the URI specified in redirect_uri with the following query parameters for you to process on your end:
state: Should be the same as the state that you specified, if it is not then you should not continue
authorized: true if the authorisation was successful otherwise false
code: The token you will need in the next step, this will only be provided if authorized was true
A refresh token is a JWT token that does not expire and allows you to get access tokens which give your app access to the end user's
account. The access token is what you will actually use to make requests, the refresh and access tokens must be stored by you to maintain
access.
You can request your tokens by sending the following HTTP request:
POST /api/v1/oauth/token/refresh?code=TOKEN&client_id=APPID&client_secret=SECRET&grant_type=authorization_code HTTP/1.1
Host: api.serble.net
Content-Type: application/json
Content-Length: 0
You need to send a POST request to https://api.serble.net/api/v1/oauth/token/refresh with the following query params:
code: The token obtained at the end of step 2
client_id: The client ID obtained in step 1
client_secret: The Client secret obtained in step 1
grant_type: Set it to authorization_code
The response will be a JSON response in this format:
{
"access_token": "<ACCESS TOKEN>",
"refresh_token": "<REFRESH TOKEN>",
"token_type": "bearer",
"expires_in": 3153600000
}
access_token: The access token is the token you use to make API requests on behalf of the user expires in 1 hour
refresh_token: The token you use to get more access tokens doesn't expire (Technically it expires in 10 years)
token_type: This will always be bearer, even if it changes it won't matter
expires_in: The amount of time until the refresh token expires, you can just ignore this and check the response from API requests to
see if the token is still valid
Send the request to the API
POST /api/v1/oauth/token/access?refresh_token=TOKEN&client_id=APPID&client_secret=SECRET&grant_type=authorization_code HTTP/1.1
Host: api.serble.net
Content-Type: application/json
Content-Length: 0
You need to send a POST request to https://api.serble.net/api/v1/oauth/token/access with the following query params:
refresh_token: The refresh token from step 3
client_id: The client ID obtained in step 1
client_secret: The Client secret obtained in step 1
grant_type: Set it to authorization_code
The response will be a JSON response in this format:
{
"access_token": "<ACCESS TOKEN>",
"refresh_token": "<REFRESH TOKEN>",
"token_type": "bearer",
"expires_in": 3153600000
}
access_token: The requested access token expires in 1 hour
refresh_token: The refresh token that you gave it
token_type: This will always be bearer, even if it changes it won't matter
expires_in: The amount of time until the refresh token expires, you can just ignore this and check the response from API requests to
see if the token is still valid
To make an API request you need to authenticate by specifying the SerbleAuth header.
SerbleAuth: App <ACCESS_TOKEN>
Substitute <ACCESS_TOKEN> with a valid access token you obtained in either step 3 or 4.