Authorization Flow

The WingCash API is protected by OAuth2 access token strings. WingCash supports two kinds of OAuth flows, Authorization Code Grant and Implicit Grant. Before an app can use either kind of flow, the developer must Create a WingCash App and configure which kinds of OAuth flows the app will use.

Authorization Code Grant

The authorization code grant flow is appropriate for a dynamic web app. This flow requires the web app to store a client secret. (It is generally not possible for a native mobile app, desktop app, or static web app to maintain the confidentiality of a client secret, so those type of apps must use the Implicit Grant flow instead.)

The steps to get an access token using this flow are as follows:

  1. Your app directs the user’s web browser to the Authorize Endpoint with query parameters.
  2. WingCash authenticates the user (using various mechanisms such as a name and password) and asks the user to let your app access WingCash in the name of the user. If the user granted permissions to your app previously and the user is still logged in to WingCash, this step is fast, nearly invisible, and requires no user interaction.
  3. WingCash directs the user’s web browser to your app’s redirect_uri with a query string containing the code parameter, an authorization code.
  4. Your app receives the authorization code and sends it in an HTTP POST to the WingCash Token Endpoint.
  5. WingCash responds to your app with an access token. (See Token Endpoint.)

Your app can then use the access token to call WingCash APIs.

Warning

An access token is very different from an authorization code. An authorization code expires quickly and is intended for a single use only. If an app tries to call the Token Endpoint with the same authorization code more than once, previously generated access tokens will be invalidated automatically.

Implicit Grant

The implicit grant flow is appropriate for a mobile app, desktop app, or static web app. This flow requires the app to operate a preconfigured redirection URI where the app will receive its access token. When an app uses this flow, the app should take precautions to prevent other apps on the same device from grabbing the access token.

The steps to get an access token using this flow are as follows:

  1. Your app opens the Authorize Endpoint (with query parameters) in a web browser.

  2. WingCash authenticates the user (using various mechanisms such as a name and password) and asks the user to let your app access WingCash in the name of the user. If the user granted permissions to your app previously and the user is still logged in to WingCash, this step is fast, nearly invisible, and requires no user interaction.

  3. WingCash directs the user’s web browser back to your app’s redirect_uri, passing the following information in the URI fragment identifier. (The fragment identifier of a URI is the part after the # symbol.)

    access_token

    The token to use in the Authorization Header for subsequent requests.

    token_type

    Always bearer for now.

    expires_in

    The number of seconds until the token’s soft expiration. After soft expiration, the token is not valid for any API calls except POST /token/refresh.

    hard_expires_in

    The number of seconds until the token’s hard expiration. Before the hard expiration, the app may attempt to refresh the token using the POST /token/refresh call.

    scope

    A space-delimited list of permissions granted to the app.

    state

    Contains the state value provided by the app.

The URI fragment is formatted like a query string. For example, if the app specifies a redirect URI of https://myapp.com/oauth-redir, the full redirect URI produced in the implicit grant flow would be something like:

https://myapp.com/oauth-redir#access_token=sometoken&token_type=bearer&expires_in=900&hard_expires_in=86400&scope=public%20view_wallet&state=xyz

Authorize Endpoint

The authorize endpoint is a web site where users enter their WingCash login credentials and authorize an app to access their profile. When the authorize endpoint finishes, it redirects back to the app that called it. The URL of the authorize endpoint is:

https://wingcash.com/authorize

The authorize endpoint expects the following query string parameters.

client_id
String of no more than 20 characters; required. The ID or name of the app requesting access.
response_type
String; required. Accepted values: code for the Authorization Code Grant flow, token for the Implicit Grant flow, or code token to support both flows at once, allowing both the browser and server to receive access tokens.
redirect_uri
String; required if token is included in the response_type parameter. Must match the redirect_uri configured for the app.
scope
String; optional. The scope is a space-delimited list of permissions to request from the user. If your app requests the mobile_device permission, WingCash will issue a device-specific access token.
state
String; optional. A CSRF token generated by the app. When WingCash redirects back to the app, WingCash will pass the state token; the app should confirm the token is unchanged to prevent abuse.
name
String; required if the mobile_device permission is requested in the scope. Contains a descriptive name of the device requesting access such as GalacticTab 10.5.
uuid
String; required if the mobile_device permission is requested in the scope. Contains a unique device identifier. Standard 36-character UUID format is preferred, but the UUID may be up to 36 characters and may contain the characters 0-9, a-z, A-Z, _, and -. If the app does not have access to a device-wide UUID, the app should generate and store its own UUID for the device.
force_login
Optional. If this parameter is set to a non-empty value (such as “true”), WingCash will require the user to log in even if the user is already logged in. Apps should provide this parameter after the user clicks a “log out” button in the app.

Warning

The app must not pass the client secret to the authorize endpoint. Doing so would reveal the client secret to all users of the app. If you have a dynamic web app, your app should pass the client secret directly to the Token Endpoint.

Token Endpoint

The token endpoint is an API call that receives an authorization code and returns an access token. The token endpoint should be called by servers only. Static web apps, desktop apps, and native mobile apps do not need this endpoint. The token endpoint URI is:

https://api.wingcash.com/token

See POST /token for the full description.

Authorization Header

The Authorization HTTP header is required for most API calls. The header line takes the following form:

Authorization: Bearer ACCESS_TOKEN

ACCESS_TOKEN is an access token received through an Authorization Flow.

An alternative to the authorization header is the access_token form variable. The authorization header is strongly preferred.

Unauthorized Response

When WingCash refuses an API call due to an access control violation, WingCash responds with a WWW-Authenticate header indicating the need for a Bearer token. Apps can look at the HTTP status code and the WWW-Authenticate header to distinguish the cause of the error:

  • When the status code is 403 (Forbidden), the app and user are authenticated but either the user or app does not have permission to access something. This may mean the app needs to request more permissions in the scope parameter passed to the Authorize Endpoint.
  • When the status code is 401 (Unauthorized) and the WWW-Authenticate header contains error="invalid_token", WingCash received an access token, but the token was expired or invalid.
  • When the status code is 401 (Unauthorized) and the WWW-Authenticate header has no error value, WingCash did not receive any access token.

OAuth2 Notes

WingCash tries to adhere to the OAuth2 Specification as closely as possible. One exception is the way WingCash handles refresh tokens. The OAuth2 spec suggests that an OAuth2 provider can issue both an access token and a refresh token, but the spec expressly forbids the provider from issuing a refresh token in an implicit grant flow (for good reason: long-lived refresh tokens are a serious liability when they are transmitted in a way that is difficult to secure.)

Therefore, WingCash invented an alternate mechanism for refreshing tokens. The POST /token/refresh API call requires an access token and a valid PIN and returns a new access token. This mechanism allows even mobile devices to refresh access tokens safely.

WingCash welcomes comments and insights on our OAuth2 implementation. Send your thoughts to support@wingcash.com.