BVG PORTAL OAuth Documentation

Introduction

APIs typically use tokens to authenticate users and do not maintain session state between requests. The Portal makes API authentication easy by using Oauth, The Portal provides a full OAuth2 server implementation. Within the Portal, authorisation and token request for developers are automated, up to the point of preserving full functionality and security of OAuth.

This documentation assumes you are already familiar with OAuth2. If not, familiarise yourself with the general terminology and features of OAuth2 before continuing.

Clients

Before a developer is granted access to the API, they must first register their application with the Portal by creating a "Client". Typically, this consists of providing the name of the application and a URL, your application can be re-direct once the user approve, the request for authorisation. The Portal automatically sets the redirect route for the developer, that will direct them to a page that will display the relevant information.

Authorising a Client

Once a client has been created, the client first needs to be authorized. Typically, developers would use their client ID and secret to request an authorisation code and access token from The Portal. The Portal does this automatically by providing the user with a authorised link, that will direct the developer to the authorisation page.

Implicit Grant Tokens

The implicit grant is similar to the authorisation code grant; however, the token is returned to the client without exchanging an authorization code. This grant is most commonly used for JavaScript or mobile applications where the client credentials can't be securely stored. When approving an authorisation request for a Client, the portal will grant the developer with an implicit token that can be used inside their application to make request to the API.

Implicit Grant Token scopes will be automatically updated as changes to the Portal API are rolled out. Implicit Grant Tokens are long-lived, however do not contain a refresh token, on token expiry a new token will have to be authorised.

Personal Access Tokens

Developers may want to issue access tokens to themselves without going through the typical authorisation redirect flow. Personal Access Tokens allow developers to experiment with the Portal API, allowing for quick and easy access to the API for development purposes.

Personal Access Token scopes will NOT be automatically updated as changes to the Portal API are rolled out. Personal Access Tokens are long-lived.

Passing Access Token

When utilising the Portals'' API, developer application's API consumers should specify their access token as a Bearer token in the Authorization header of their request. For example: 

                            
                                //Using the Guzzle HTTP library
                                $response = $client->request('GET', '/api/testAuthorisation', [
                                    'headers' => [
                                        'Accept' => 'application/json',
                                        'Authorization' => 'Bearer '.$accessToken,
                                    ],
                                ]);
                            
                        
                            
                                //Using the standard .Net HttpClient
                                HttpClient client = new HttpClient();
                                client.DefaultRequestHeaders.Add("Accept", "application/json");
                                client.DefaultRequestHeaders.Add("Authorization", accessToken);;

                                Uri uri = new Uri('/api/testAuthorisation');
                                var response = await client.GetAsync(uri);
                                var result = response.Content.ReadAsStringAsync().Result;
                                var testAuth = JsonConvert.DeserializeObject(result);
                            
                        
                            
                                //Using JQuery ajax
                                $.ajaxSetup({
                                    headers: {
                                        'Accept' : 'application/json',
                                        'Authorization' : "Bearer " + accessToken,
                                    }
                                });

                                $.ajax({
                                    url: '/api/testAuthorisation',
                                    type: 'GET',
                                    success: function(response) { },
                                });