-
Notifications
You must be signed in to change notification settings - Fork 0
Api: Authentication
Onscribe uses OAuth2 for authentication. OAuth2 is a protocol that lets external apps request authorization to private details of the service without getting their password. This is preferred over Basic Authentication because tokens can be limited to specific types of data, and can be revoked by users at any time.
All developers need to create a product before getting started. A registered product is assigned a unique Client ID and Client Secret for OAuth authentication. The Client Secret should not be shared.
Note that there are three different levels of authentication you can use:
- User Auth, which returns a user-specific token for your client app
- Application Auth, which returns an application level token for your client app
- CLI Auth, where authentication is on a user level using username/password credentials
This is a description of the OAuth2 flow from 3rd party web sites.
GET https://onscri.be/oauth/authorize
Parameters
| Name | Type | Description |
|---|---|---|
| client_id | string | Required. The client ID you received from Onscribe when you registered. |
| redirect_uri | string | The URL in your app where users will be sent after authorization. See details below about redirect urls. |
| scope | string | A comma separated list of scopes. If not provided, scope defaults to an empty list of scopes for users that don’t have a valid token for the app. For users who do already have a valid token for the app, the user won't be shown the OAuth authorization page with the list of scopes. Instead, this step of the flow will automatically complete with the same scopes that were used last time the user completed the flow. |
| state | string | An unguessable random string. It is used to protect against cross-site request forgery attacks. |
If the user accepts your request, Onscribe redirects back to your site with a temporary code in a code parameter as well as the state you provided in the previous step in a state parameter. If the states don’t match, the request has been created by a third party and the process should be aborted.
Exchange this for an access token:
POST https://onscri.be/oauth/access_token
Parameters
| Name | Type | Description |
|---|---|---|
| client_id | string | Required. The client ID you received from Onscribe when you registered. |
| client_secret | string | Required. The client secret you received from Onscribe when you registered. |
| code | string | Required. The code you received as a response to Step 1. |
| redirect_uri | string | The URL in your app where users will be sent after authorization. See details below about redirect urls. |
Response
By default, the response will take the following form:
access_token=e72e16c7e42f292c6912e7710c838347ae178b4a&token_type=bearer
You can also receive the content as a JSON output depending on the grant_type and/or the existence of a redirect_uri
{"access_token":"e72e16c7e42f292c6912e7710c838347ae178b4a", "token_type":"bearer"}
The access token allows you to make requests to the API on a behalf of a user.
GET https://onscri.be/api/...?access_token=...
You can pass the token in the query params like shown above, but a cleaner approach is to include it in the Authorization header
Authorization: Bearer <token>
For example, in curl you can set the Authorization header like this:
curl -H "Authorization: Bearer <token>" https://onscri.be/api/...
Use Basic Authentication to create an OAuth2 token using the interface below. With this technique, a username and password need not be stored permanently, and the user can revoke access at any time. (Make sure to understand how to work with two-factor authentication if you or your users have two-factor authentication enabled.)
The redirect_uri parameter is optional. If left out, Onscribe will redirect users to the callback URL configured in the OAuth Application settings. If provided, the redirect URL's host and port must exactly match the callback URL. The redirect URL's path must reference a subdirectory of the callback URL.
Scopes let you specify exactly what type of access you need. Scopes limit access for OAuth tokens. They do not grant any additional permission beyond that which the user already has.
For the web flow, requested scopes will be displayed to the user on the authorize form.
NOTE: Your application can request the scopes in the initial redirection. You can specify multiple scopes by separating them with a comma:
https://onscri.be/oauth/authorize?
client_id=...&
scope=user,public_repo
Note#2: Currently scope has no effect for the service but as we upgrade the API it may in the future, in which case we will detail the different scopes here...
There are a few things that can go wrong in the process of obtaining an OAuth token for a user. In the initial authorization request phase, these are some errors you might see:
If the OAuth product you set up has been suspended (due to reported abuse, spam, or a mis-use of the API), Onscribe will redirect to the registered callback URL with the following parameters summarizing the error:
{
error: "invalid_request",
message : "Authentication failed: The request is missing a required parameter, includes an unsupported parameter or parameter value, or is otherwise malformed."
}
Please contact support to solve issues with suspended applications.
A common occurrence is that the request may not contain all the necessary information to proceed. In such case the request will end abruptly with the following output:
{
code: 400,
error: "missing_parameter",
message : "Missing required parameter: <Array if missing parameters>"
}
If the client_id and or client_secret you pass are incorrect you will receive this error response.
{
code: 401,
error: "invalid_client",
message : "Authentication failed: The client identifier provided is invalid."
}
To solve this error, go back and make sure you have the correct credentials for your oauth application. Double check the client_id and client_secret to make sure they are correct and being passed correctly to Onscribe.
If the verification code you pass is incorrect, expired, or doesn't match what you received in the first request for authorization you will receive this error.
{
code: 401,
error: "invalid_code",
message : "Authentication failed: The verification code provided is invalid."
}
To solve this error, start the OAuth process over from the beginning and get a new code.
More information on the errors and in the inner workings of the OAuth2 implementation in general is available at connect OAuth2 which is the underlying open source library providing this functionality.