Authorization Pin Code Grant

The authorization pin code grant type is used to obtain both access tokens and refresh tokens and is optimized for native clients. The native client requests a pin code connected to the client id. This pin code is used to activate access for a resource owner for the specific native client. Activation is done using a web browser and can be accomplished on any unit. The native client will then poll the pin code for a grant/reject by the resource owner that follows the activation url. If the resource owner grants access for the application, the pin code will return a access code that the client can use to retrieve the tokens.

Pin code request

The first step for the Client application is to request a pin code This is done using a get request as follows

 GET /apiv2/oauth/authorize?response_type=code&code_type=pin
 Host: imagevault.domain.com
 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

Parameter Name	Description
response_type	Defines the type of grant to be requested. Must be set to "code".
code_type	Defiles the action to perform. Must be set to "pin"

• The client MUST authenticate with the client credentials using HTTP basic authentication.
• The client used MUST NOT have a registered RedirectUri to be able to generate pin codes.

Pin code response

If authentication is successful and all parameters are valid, then the service will return a pin code response on JSON format. The pin code contains the following properties

Parameter Name	Description
pin	contains the generated pin code
expires_in	The number of seconds that this pin is valid

The pin code is valid for a short time so the activation step needs to be performed within that time frame, otherwise a new pin code must be retrieved.

Activation

When the pin code is received, the resource owner needs to activate it by navigating to the activate url in a web browser and supplying the pin code. Replace the word pin with the actual pin received in the pin code response.

 GET /activate/myPin
 Host: imagevault.domain.com

The resource owner is then required to log in and to approve the client to use the ImageVault application.

Poll Pin code

While the pin code is being activated, the client application can perform polls using the following url

 GET /apiv2/oauth/authorize?response_type=code&code_type=pin&pin=myPin
 Host: imagevault.domain.com
 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

Parameter Name	Description
response_type	Defines the type of grant to be requested. Must be set to "code".
code_type	Defiles the action to perform. Must be set to "pin"
pin	The pin code received in the pin code response.

• The client MUST authenticate with the client credentials using HTTP basic authentication.

Poll pin code response

The poll can have three different outcomes

1. Pin code has not yet been granted/rejected
2. Pin code has expired- or access via pin code has been rejected
3. Access via pin code has been granted

The response is returned on json format with the following schema

Name	Available in	Description
state	all	tentative/invalid/granted based on the scenarios above
code	granted	The authorization code generated by the authorization server. The client MUST NOT use the authorization code more than once. If an authorization code is used more than once, the authorization server MUST deny the request and SHOULD revoke (when possible) all tokens previously issued based on that authorization code. The authorization code is bound to the client identifier and redirection URI. The code consists of a up to 30 characters case sensitive string.
expires_in	granted	The number of seconds that this code is valid

Access token request

When you have retrieved the authorization code you can request an access and request token as described in Authorization Code Grant, Access token request