Environments & authentication

To ensure the best accessibility across platforms, Wingspan built its REST API with OpenAPI specification version 3.0.0. The Wingspan API is resource-oriented and accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Wingspan makes two deployments of the API available to you:

The staging deployment can be used for testing, while the production deployment is used for live transactions. Both deployments require appropriate headers when calling the API. There are three headers that must be passed for each API call:

• Content-Type: application/json
• Accept: application/json
• Authorization: Bearer

For example:

> \curl GET https://api.wingspan.app/payments/payable
> \--header Accept: application/json  
> --header Content-Type: application/json  
> --header Authorization: Bearer eyJhbGci...\

Authentication

Bearer Token:

• Function: A type of token that is generated in application and can be included in the header of HTTP requests.
• Usage : Sent in the HTTP header. The server validates the token and determines if the request is authorized.

The API uses bearer authentication for identifying callers and authorizing access to requested resources. Bearer authentication (also called token authentication) is an HTTP authentication scheme that involves security tokens called bearer tokens. The name Bearer authentication can be understood as, “give access to the bearer of this token.” The bearer token is a cryptic string generated by the server in response to a token generation request. The client must pass this token in the Authorization header when making requests to protected resources.

The format of the bearer auth header is:

Authorization: Bearer <API Token>

Generate an API key

Generating an API key is the mandatory first step in calling the Wingspan API and is a simple task that is completed in the web application. However, before you can generate the API key, you must create a Wingspan account, if you have not done so already. For more information about creating a Wingspan account, see Create a Wingspan account.

To generate an API key

1. Log in to Wingspan and go to the Data & Integrations drop-down in the side menu.
2. Under Data & Integrations choose Developer.
3. On the developer page, click Generate new token. The New API token popup appears.
4. In the New API token popup, you can assign some identifying information to the API in Wingspan by indicating that for which the token is used. This is optional, but recommended if you have multiple keys. For example, you might have one key for a testing environment and another for a Production environment.
5. After the key is generated, it displays on the developer page.
6. To begin using the key to make API calls, click Copy to retrieve the key and paste it directly into a call that you are about to make. For security reasons it is not recommended that you copy and save the key outside of Wingspan. You can retrieve the key from its secure location on the Developer page in Wingspan.
7. After your API key is generated, test that it is valid by using the following example call. The example call is demonstrated in cURL:

> curl -i '<https://api.wingspan.app/users/session/token/><API Token>' \\
> H 'authority: api.wingspan.app' \\
> H 'accept: application/json, text/plain, _/_' \\
> H 'authorization: Bearer <API Token>'

An expired or invalid token results in an error response:

> HTTP/2 403
> ...
> {"error":"Session expired"}

If the token is still valid, a 200 level status is returned:

> {  
>   "token":"<API Token>",  
>   "expiration":"<Expiration as ISO Timestamp>",  
>   "sessionType":"User",  
>   "userId":"<UserId corresponding to Token>"  
> }

You are now ready to start using the Wingspan API.