API Basics

Wingspan exposes a RESTful API whose reference documentation is available here.

The API’s only request / response format is JSON for message bodies, and the appropriate headers should be used when calling the API:

Content-Type: application/json
Accept: application/json

Authentication

The API uses bearer authentication for identifying callers and authorizing access to requested resources. The format of the bearer auth header is:

Authorization: Bearer <API Token>

To verify whether a token is valid, the following API call is useful:

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 will result in an error response:

HTTP/2 403 
...

{"error":"Session expired"}

A valid token will result with status information (as per the reference):

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

Authentication as a Requesting User

A user who’s granted access to an account (via the Teams feature) is called a “Requesting User” — rather than creating an API key directly on a production account, a best practice is to create an “API User” by giving them the required permissions on the source account.

Key Terms