Token API Calls

Use these API calls to create and refresh access tokens.

Create a Token

POST /token

This is the OAuth2 Token Endpoint used in the Authorization Code Grant flow (but not in the Implicit Grant flow.) It accepts an authorization code and returns an access token.

Warning

When your app uses the new access token issued by this call, WingCash will no longer accept old access tokens previously issued for the same combination of app, profile, and personal profile.

Permission Required:
 

None.

Request Headers:
 
  • Authorization – Contains the client ID and client secret in HTTP basic authentication format. This header is preferred, but you may alternatively pass the client_id and client_secret as form parameters.
  • Content-Typeapplication/x-www-form-urlencoded
Form Parameters:
 
  • grant_type – Must be authorization_code.
  • code – The authorization code returned by the Authorize Endpoint.
  • redirect_uri – The same redirect_uri as the redirect_uri passed by the app to the Authorize Endpoint.
  • client_id – Alternative to the Authorization header. Contains the ID or name of the app. (Not the app’s title.)
  • client_secret – Alternative to the Authorization header. Contains the app’s client secret.
Status Codes:
  • 200 OK – Successful. The response body is an AccessTokenInfo object.
  • 400 Bad Request

    The request is invalid. The response body is a JSON object with these attributes:

    error
    One of invalid_request, invalid_client, invalid_grant, unauthorized_client, unsupported_grant_type, or invalid_scope.
    error_description
    An ASCII description of the error intended for developers only.

Refresh a Token

POST /token/refresh

Refresh an access token that has not reached hard expiration. The user’s password or PIN is required. The new token will have a new soft expiration but the same hard expiration as the old token.

If this call returns a 401 HTTP response code, use the standard Authorization Flow to get a new access token.

This token refresh mechanism is different from the refresh mechanism suggested by the OAuth2 spec. See OAuth2 Notes.

Note

Your app must not store user passwords. See the Authentication API Rules.

Warning

When your app uses the new access token issued by this call, WingCash will no longer accept old access tokens previously issued for the same combination of app, profile, and personal profile.

Warning

After five failed refresh attempts, WingCash will no longer accept attempts to refresh the access token. The user may have to log out and log in again to re-authorize the device or app.

Permission Required:
 

None.

Request Headers:
 
Form Parameters:
 
  • version – Optional. If provided, must be 1.
  • access_token – Optional alternative to the Authorization Header.
  • password – The authenticated user’s password. Provide either the password or the PIN.
  • pin – Optional. The authenticated user’s PIN.
Status Codes:
  • 200 OK – Successful. The response body is an AccessTokenInfo object.
  • 400 Bad Request – The parameters are not valid. The response body contains an InvalidRequest object. The error may be invalid or incorrect_pin.
  • 401 Unauthorized

    The access token is missing, not valid, or the hard expiration has passed. The following error values may be returned in the JSON response body:

    incorrect_password
    The password was incorrect.
    incorrect_pin
    The PIN was incorrect.
    refresh_locked
    Someone tried and failed to refresh the access token too many times.

    See Unauthorized Response.

Select a Profile

GET /token/selectable

List the profiles that the authenticated personal profile can select through the GET /token/select/(string:profile_id) API call.

Note

The GET /wallet/info API call provides the same list of selectable profiles and more, but this call requires only the select_profile permission, not the view_wallet permission.

Permission Required:
 

select_profile. See Permissions.

Request Headers:
 
Query Parameters:
 
  • version – Optional. If provided, must be 1.
  • access_token – Optional alternative to the Authorization Header.
Status Codes:
  • 200 OK

    Successful. The response body is a JSON object with these attributes:

    profiles
    A list of Profile objects the authenticated personal profile can select.
  • 401 Unauthorized – The access token is missing, not valid, or the hard expiration has passed. See Unauthorized Response.
  • 403 Forbidden – The access token is valid but the app is not authorized to access this function.
GET /token/select/(string: profile_id)

Get an access token for a specified profile. Using this API call, people can use your app with a business profile they manage.

If your app attempts to get a token for a profile not managed by the authenticated personal profile, this call returns a 403 (forbidden) HTTP response code.

Warning

When your app uses the new access token issued by this call, WingCash will no longer accept old access tokens previously issued for the same combination of app, profile, and personal profile.

Permission Required:
 

select_profile. See Permissions.

Request Headers:
 
Query Parameters:
 
  • version – Optional. If provided, must be 1.
  • access_token – Optional alternative to the Authorization Header.
Status Codes:
  • 200 OK – Successful. The response body is an AccessTokenInfo object.
  • 400 Bad Request – The parameters are not valid. The response body contains an InvalidRequest object. The error is invalid.
  • 401 Unauthorized – The access token is missing, not valid, or the hard expiration has passed. See Unauthorized Response.
  • 403 Forbidden – The access token is valid but the app is not authorized to access this function. The error code may be insufficient_scope, not_manager, not_available, or app_denied.

Log Out

POST /token/logout

Stop accepting the access token provided in the authorization header, as well as all tokens for the same personal profile and app. Apps only need to call this once to invalidate all access tokens (including those issued by /token/refresh and /token/select) for a personal profile.

After this call, the next time your app calls the Authorize Endpoint, your app should provide the force_login=true parameter so that a different user can log in.

This API call accepts tokens that have passed soft expiration, but not tokens that have passed hard expiration.

Permission Required:
 

None.

Request Headers:
 
Form Parameters:
 
  • version – Optional. If provided, must be 1.
  • access_token – Optional alternative to the Authorization Header.
Status Codes: