Documentation

error_outline
Not sure how to use the API? Read over the basic functionality of the API here (click me).

Authentication

Most API endpoints require an OAuth access token.


OAuth

OAuth 2.0 is a simple and secure authentication mechanism. It allows applications to acquire an access token for the API via a quick redirect to the our site. Once an application has an access token, it can access a user's information.


Authentication with OAuth can be accomplished by adding the token parameter with a user's access token to a request.

token=**access_token**

OAuth Web Flow

Applications can easily acquire an OAuth access token for an end-user by following these steps:

  • Register your application here – your application will be assigned a client_id and client_secret.
  • Redirect the user to https://api.theartex.net/v1/oauth/authorization/, using the client_id, response_type, scope and redirect_uri (required only when response_type has the value of code) parameters to pass your client ID, the response you would like to receive, the scope of access and the URI to redirect the user to upon authentication.
  • Web applications can use the response_type parameter with a value of code to request an authorization code used to request access tokens
    • An example redirect URL looks like:
      https://api.theartex.net/v1/oauth/authorization/?client_id=...&response_type=code&scope=...&redirect_uri=http://myexamplewebapp.com/oauth_page
    • Upon authorizing your application, the user is directed to the page specified in the redirect_uri parameter. We append a code parameter to this URI that contains a value that can be exchanged for an OAuth access token using the /v1/oauth/token endpoint documented below. For example, if you pass a redirect_uri value of http://myexamplewebapp.com/oauth_page, a successful authentication will redirect the user to http://myexamplewebapp.com/oauth_page?code=....
    • Use the /v1/oauth/token API endpoint documented below to acquire an OAuth access token, passing the code value appended by the API to the previous redirect and the redirect_uri value that was used previously. This API endpoint will return an OAuth access token, as well as information about the access token.
  • Desktop and mobile applications can use the response_type parameter with a value of token to request a token directly after authentication that can be extracted from the URI
    • An example redirect URL looks like:
      https://api.theartex.net/v1/oauth/authorization/?client_id=...&response_type=token&scope=...
    • Upon authorizing your application, the user is directed to the callback of your application. We append special token parameter to this URI that contains an access token. For example, if you have a callback value of http://myexamplewebapp.com/oauth_page, a successful authentication will redirect the user to http://myexamplewebapp.com/oauth_page#token=....

An example request might look like:

POST /v1/oauth/token HTTP/1.1
Host: api.theartex.net
Content-Type: application/x-www-form-urlencoded

client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&code=CODE&grant_type=authorization_code

And an example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "code": 200,
    "host": HOST,
    "method": "POST",
    "data": {
        "access_token": ACCESS_TOKEN,
        "token_type": "bearer",
        "expires_in": 86400,
        "refresh_token": REFRESH_TOKEN,
        "scope": SCOPE,
        "uid": UID,
        "info": {
            "username": USERNAME,
            "email": EMAIL
        }
    }
}

Parameters for OAuth Web Flow

  • client_id – your application's client id
  • client_secret – your application's client secret
  • code – the OAuth verification code acquired via the OAuth authentication protocol
  • redirect_uri – the URI to which the user was redirected to after authentication
  • response_type – the type of response your application wants to receive
  • grant_type – the type of grant your application wants to access

Response Value

By default, we'll return a JSON dictionary and appropriate Content-Type response header

  • access_token – the OAuth access token for the specified user
  • token_type &ndash the type of access token
  • expires_in &ndash the amount in seconds until the access token expires
  • refresh_token &ndash a token that can be used to request a new access token
  • scope &ndash the scope of the authorization
  • uid &ndash a unique id that represents the OAuth access token
  • username &ndash the username of the specified user
  • email &ndash the email of the specified user