Acccess Token Examples

How the client application gets an access token is defined by the "grant type" requested by the client application. The OAuth2 protocol defines four grant types.

Authorization Code Grant Type

The client application directs the user's (the resource owner) web browser to the resource server (VisualVault) where the user logs in unless already authenticated. The client application sends its client id (API key) and client secret (API secret) to VisualVault along with a redirect URL where the client application is listening for a response from VisualVault. VisualVault prompts the user with a screen where the user can grant access to the client application. If the user grants acccess to the client application, VisualVault sends the client application an 'Authorization Code'. The client application then sends the authorization code, client id, and client secret along with the same redirect URL to the VisualVault access token URL. VisualVault authenticates the client application, validates the authorization code, and verifies the callback URL is identical to the URL used to request the authorization code.

The Authoriation Code grant type prevents the client application from knowing the user's credentials and is appropriate for web-server based applications which can receive the authorization code and access token via a callback URL. A refresh token is sent with the access token and the client application is responsible for storing the refresh token associated with each user. The persisted refresh token may be used to request a new access token up to the point the refresh token has expired. VisualVault allows you to define the refresh token expiration period when you register an application. The default refresh token expiration period is 24 hours.

Implicit Grant Type

The Implicit grant type is intended for use where the client application is JavaScript running in a web browser. In this scenario, using the client secret (API secret) is not an option because the client secret would be exposed to anyone examining the script. The client application must be pre-registered along with a pre-defined callback URL. The client application sends its client id, redirect URL, requested scope, and optional local state value to the access token URL. The state value should be a unique value used for each request and verfied by the client application when VisualVault sends back an access token (the state value is returned to the client application along with the access token). The state value is used to prevent cross-site scripting exploits.

The client id (API key) and callback URL are used to authenticate the client application, the user (resource owner) is prompted to grant access to the client application. If the user grants access, an access token is sent directly back to the redirect URL. The implicit grant type does not support the use of refresh tokens.

Resource Owner Password Credentials Grant Type

The resource owner password credentials grant type is suitable in cases where the user (resource owner) has a trust relationship with the client application. A mobile device application is an example of a suitable use case for this grant type where the user is prompted to enter their credentials and the client application has direct access to the user credentials. The client application directly exchanges the user credentials for an access token and refresh token. The client application may optionally persist the refresh token rather than storing the user credentials and use the refresh token for subsequent access token requests. The access token expiration time value is in seconds from UTC.

    curl -X POST \
	-H "Content-Type: application/json" \
	-d '{
		  "client_id": "fbb02e0c-2e97-4527-a6d7-9438d8b7b23c",
		  "client_secret": "bBb+IlcCV5duoyyHvrYYamSrDVMGf+rgJ4Gbhn6R7N4=",
		  "username": "vault.config",
		  "password": "p",
		  "grant_type": "password"
		}' \ 

     https://demo.visualvault.com/oauth/token
            
     Response:
    
     {
     "access_token":"zc2tf5I6P90aeEWu7dp3JzDwhuix1hJcUwMvWcmLX7hZzghueVFsWW9BG7KVdsowwqhGJwgY-cqDED9gJ608jfUUPGZ36TaHGdvNhUfBToKjxRLEEMN0XbemsuVTX36HmT7iMBxAPEcj-TgAYxNze7XCuMS6D57NMqJ91-nu89Z4m2TNrJvBaNzA0f_w52-xFKyXyWc_mYdTsMyowHlnw4WnLGz1yTo247KooWxvtJUrYhpGU6fN8YnOZYnBAvTS5T7PmtarHZmQKbEvid7hMU5f4Wf1RS6rmz0PaGenQY8jsCXm",
     "token_type":"bearer",
     "expires_in":1199,
     "refresh_token":"DKgYrltwmT6YJ_vmnqBGx_R7ynG6wXhBYOt9c7w64bYr8kxxKV5vgcXNwGE21isagAwE8Oz8opopHAiy-1uKvpLBPdgQ3X3DIzZZW9GzKsgt3DxdCxT6q4C3cRpfISBkkrqU4afqkE3pEskFVJF1tJvIBu4JszCiYAvNuMmq1N_MmfWu8kEj4sV5c5YxJcleeaaBhucr0mZcdu2Rjc4bJIxvtFhc7nLQ96EcL144KOge30GzKkU-XX5qTj7NDoeLiVMvOjyV4uQTK1wBP8UPhScsMKRIi7BqmDlJCjAvVsNrV0ZC"
     }

      

Client Credentials Grant Type

The client credentials grant type is used in cases where the client application directly owns resources. This is essentially a 'service account' scenario where the client application is a VisualVault account rather than a registered application. The client appliation sends its client id (API key) and client secret (API secret) and directly exchanges its credentials for an access token and refresh token. The access token expiration time value is in seconds from UTC.

    curl -X POST \
	-H "Content-Type: application/json" \
	-d '{
		  "client_id": "fbb02e0c-2e97-4527-a6d7-9438d8b7b23c",
		  "client_secret": "bBb+IlcCV5duoyyHvrYYamSrDVMGf+rgJ4Gbhn6R7N4=",
		  "grant_type": "client_credentials"
		}' \ 

     https://demo.visualvault.com/oauth/token
            
     Response:
    
     {
     "access_token":"n_03-G_B7Q7Xav9xLcTA3BHcVgbXSMeJ5wE6NyXXEhpM5uoCx4MEBunwkDI-HzqUgYk64MMwy1sD73hnpGMnbuv-u_PdrjBSF9lCsjFyuztI3KWGv8Ej3vsefvALu84hXCdydkSZ_bB-PXE4avBpkLcaXj3eaX4XwvPRfW63lixXPQ_6rGtR6SBzpiCK8gBA5YIQuDOM64y5Un16oKFvL5xSrszS6HI4_j7e62RoeGnVLzjEkCuWedyz7dpOzk4vBPlWopS3jFv4mX2H8MUKXysC5qjggCR_na1b59ZJAs1zxi63",
     "token_type":"bearer",
     "expires_in":1199,
     "refresh_token":"8LkjAlnGY5YjA_m-9K8z7fGSdhoyDPAz9YWh7iM-IhqKWIXCK2NpOem49DJMZ7gwJoDeywZ91dWEoKatnSL-fPVEVAIDB7lJJy62BRLT8eAUDRDmc2IowoJ-80NNtIcEstYkhUtUiodnC4jfbmpbKTZgOlxoAcHKZawvJ7lY_VNKZD0rIiMDZdynVZyGdPLWwQDH361h-OuNiLlUS_n3rnFTVz5t24YMZVv7qkA7cSmv7gk7D-ohiswIslermohaM67UsmhSh74ZijSUB568J-T_8iwZIH76jtHCuTk-r-_bImSi"
     }