Authorizing Access for Applications

When a request is received via the API the following checks are performed before it is granted access to the resource data:

1. Which application is making the request?
2. Who is the resource owner?
3. Has the application been granted access by the resource owner?
4. Is the operation requested by the request allowed by the permissions granted by the resource owner for that resource set to that application?

The first two points are concerned with authentication, and the remainder with authorization.

The API requires that applications are registered on this system by developers so that they can be given the required identification and credentials in order to work with this system of authentication and authorization.

Authentication Protocols

The API supports the OAuth2 protocol and certain resources (e.g. feeds) additionally support a simpler API Key authorization. These are described in the following sections.

Oauth2 Protocol

The API supports the OAuth2 protocol specificially the authorization code, and implicit grant flows only, and does not support refresh tokens. This protocol enables the resource owner to grant a revokable access to their resources to third party applications, for a specified time period, without having to divulge their login credentials.

OAuth2 Authentication

The OAuth2 authentication system does not require the resource owner to give his/her login credentials to the application. Instead it uses a token-based system which has these advantages:

• The resource owner can change his/her password without having to notify the application or application developers.
• The resource owner can authorize limited access to his/her information
• The resource owner can revoke access from the application at any time.

These steps are taken to safeguard the integrity and privacy of the resource owner's information.

OAuth2 Authorization

Before an application can successfully access a resource owner's information, the resource owner must grant it access. In the OAuth2 protocol, the user/resource owner would visit the website of the application and either download it or access it via a web browser. The browser will be redirected to this website where the user/resource owner will be presented with a page requesting authorizaton for the application. The page will show which resource set(s) the application is requesting access to, and also what permissions (read, update etc.) the application requires. The resource owner can then either grant or refuse access.

If access is granted, the application will be issued with an access token. The access token needs to be sent with all subsequent API requests; see next section.

Sending OAuth2 Authorization Information

When sending the access token to the server with the API request it is recommended that the HTTP Authorization header be used to hold the access token. Although the server will accept it in the query string and in form-urlencoded data, it separates concerns better to have them in the header.

To send the access token as a query string parameter, simply include use the name=value form, for example:
access_token=T4i9Dbrpz280xbYzp8EyJ2f7XWp5VmlepK8Eqc

To use the HTTP Authorization header, send it as a bearer token, for example:

Authorization: Bearer T4i9Dbrpz280xbYzp8EyJ2f7XWp5VmlepK8Eqc

OAuth2 Endpoint URIs

The following are the URIs to use as part of requesting OAuth authorization for this API:

1. The authorize endpoint: Redirect the user's browser to this endpoint so that the user can grant access to the application
   https://api.vendexo.com/api/auth/oauth/v2/authorize/
   Required query string parameters

   client_id

   The id code identifying the client application.

   response_type

   Must be either code or token. Specify code if using the authorization-code flow, and token to request the Implicit flow. Consult the OAuth2 reference above for more information about these flows.

   Optional query string parameters

   state

   A value which can be used by the client to maintain state between the request and the redirect back. The value is not used by the authorization process per se; the authorization server includes this value when redirecting the user agent (browser) back to the client. It is recommended that the parameter be used for preventing cross-site request forgery (CSRF) attacks.

   redirect_uri

   If a redirect URI is specified it must match one of the valid redirect URIs specified when the application was registered. If omitted, the default redirect_uri specified in the application registration will be used.

2. The access_token endpoint: To obtain the access token, when using the authorization-code flow, the client application must send a POST request to the following URI:
   https://api.vendexo.com/api/auth/oauth/v2/access_token/
   The post data must contain the grant_type parameter (set to "authorization_code") and the code parameter set to the authorization code which the authorize endpoint generated. The redirect_uri parameter must have a value matching that specified in the authorize step. If the client is confidential, it must also include the client_id and client_secret which the app developer can retrieve from the app registration screen. Ideally these would be specified using a HTTP Basic authentication header, with the form-urlencoded client_id used as the username part and the form-urlencoded client_secret as the password, as per the OAuth2 spec RFC 6749 section 2.3.1. Client Password. If the client is not confidential, it must include the client_id as part of the POST data. The response will contain the access token, and if a time limit on the token has been specified, the response will contain an "expires_in" value in seconds until expiration.

Note: Since secret keys are passed as part of the above steps, the application must use an encrypted transport layer when making these request, e.g. by using https:.

Authorization Revocation

Application developers should note that resource owners can revoke access to the application at any time by going to their account settings and clicking on "Applications". They can also, when authorizing the application, specify a time period for which the authorization is valid.

API Key Authentication

Certain resources (e.g. feeds) also support Api Key authentication. This simplified form of authentication simply includes an API key with the request. There is an implicit grant given to the associated resource when this form of authentication is used. The client can either use the HTTP Authorizaton header or a query string parameter to convey the API key. It is less secure than using the OAuth2 protocol described above. An example using the Authorization header:

Authorization: ApiKey 123456790

Alternatively, using a query parameter, simply use: apikey=1234567890 replacing 1234567890 with your own API key.