API Security

Authentication

Access to Passport’s public APIs is restricted to authenticated applications only. Partners are granted credentials when they register and will use those credentials to authenticate their application with Passport’s identity provider. Once the application has successfully authenticated, Passport will authorize that application to access the appropriate resources (APIs).

Authorization

Once authenticated, an application will be granted access to the approved public APIs. This authorization is accomplished by issuing the application an access token. The access token will include a limited set of scopes that allow the application to retrieve and act on Passport’s protected resources. Each subsequent call to an API must include this access token.

To authenticate and retrieve the access token, applications will use the Client Credentials Grant flow described by OAuth 2.0.

Using the Client Credentials Grant

  1. Applications must make a request to Passports authorization server token endpoint: /shared/access-tokens, providing their client_id and client_secret.
curl -X POST \
  https://.../shared/access-tokens \
  -H 'Cache-Control: no-cache' \
  -d 'grant_type=client_credentials&client_id=<your_client_id>&client_secret=<your_client_secret>&audience=public.api.passportinc.com'

Note: The audience parameter must include the identifier of the API set that the application is requesting access to. In most cases this will be: public.api.passportinc.com. When an API requires a different value, it will be listed in the API documentation.

  1. In response, Passport will create and return an access token that contains a collection of approved scopes for that application. This token will be valid for a limited period of time, specified by the expires_in field in the response. See Access Token Expiration for additional details.
{
    "access_token": "<your_access_token>",
    "scope": "read:resource write:resource",
    "expires_in": 86400,
    "token_type": "Bearer"
}
  1. Applications then use that access token to make requests to other protected resources. The access token must be included in the Authorization header as a Bearer auth token. Note, the same access token can be leveraged for multiple API requests to the same set of public APIs. You do not need to request a new token until the old token expires.
curl -X POST \
  https://.../parking/zones \
  -H 'Cache-Control: no-cache' \	
  -H 'Authorization: Bearer <your_access_token>' \
  -d 'latitude=123556&longitude=987653'`

If the access token includes the required scopes to access the protected resource (zones in this example) then the API will execute and respond accordingly.

Access Token Expiration

Access tokens will live anywhere from 1 hour to 1 day. When the token expires, the request will return an HTTP 401 error (unauthorized). In response to this error, applications must fetch a new access token per the instructions above. Once the new access token is received it can then be used to call the Platform APIs until it also expires.

Scopes

Passport restricts course-grained access to resources using basic read and write scopes. These scopes are pre-assigned to each application at registration time. They are then embedded within the access token and cannot be altered. Applications may not request additional scopes outside of the registration workflow.

If an application attempts to access a resource that it does not have a scope for, the resource will return an error.

Secure connections

All API requests must be made using HTTPS. Any calls made over an unsecure connection will be rejected.

Rate limits

Passport may impose rate limits upon each API to protect the integrity and stability of the Platform for all tenants. These limits will be defined during the Client registration process. Limits will be based upon the expected utilization and burst thresholds for each application.

Rate limits will be implemented in two ways:

  1. Throttling access by limiting the number of requests per second that an application can invoke.
  2. Applying a quota on the total number of requests an application can invoke in a given day.

If an application exceeds its allocated rate limit, Passport will respond with an HTTP 429 - Too Many Requests status code. Upon catching this error, the application can resubmit the failed request.