API Overview
Environments
| Environment | URL | Purpose |
|---|---|---|
| Staging | https://api.playmetric.io/gateway |
Testing & validation |
| Production | https://api.playmetrics.com/gateway |
Live operations |
Authentication
An environment specific API Gateway key will be provided by the PlayMetrics product team for use with the APIs. The API key will allow an API client application to utilize the /auth endpoint to receive a JWT (JSON Web Token). The JWT is then required for communicating with the other PlayMetrics public APIs.
Authentication Workflow
- Use the secret API Key with the /gateway/v1/auth endpoint to retrieve the API Gateway JWT.
- Store and use the supplied API Gateway JWT with the /gateway/v1/clubs/... endpoints.
API Key - Place the secret API Key in X-API-KEY header when using the /auth API Gateway endpoint.
/auth - The /auth endpoint is used to generate a temporary API Gateway JWT for use with the /clubs/... endpoints.
API Gateway JWT - When using the gateway /clubs/... endpoints, use the Authorization header containing "Bearer <token>".
Embedded User Authentication
| Environment | User Authentication URL (embed) |
|---|---|
| Staging | https://auth.gateway.playmetric.io/index.html |
| Production | https://auth.gateway.playmetrics.com/index.html |
In cases where a PlayMetrics user is required to grant the client application access to API data, a user authentication flow is necessary. When this is the case, the client application will not be able to access the /gateway/v1/clubs/... endpoints until an authenticated user grants the access. The user authentication flow requires the use of the PlayMetrics user authentication page and both an API Gateway JWT and a PlayMetrics User JWT. These are necessary to access the /gateway/v1/user/... API endpoints.
User Authentication and Access Granting Workflow
- Within the client application launch a modal window and embed the PlayMetrics user authentication page.
- Upon successful login the embeded authentication page will emit a PlayMetrics User JWT to the opener.
- Store the PlayMetrics User JWT.
- Perform the standard API Authentication workflow (above) to retrieve API Gateway JWT.
- Using both the API Gateway JWT and PlayMetrics User JWT access the /gateway/v1/users/... endpoints.
- Make post(s) to /gateway/v1/users/.../access endpoints to grant the client application access to the requested entity.
- Once access is granted by the user to the entity (team or club) the client application will no longer need to use the user authentication flow to access the entity. The standard authentication flow for access to /gateway/v1/clubs/... endpoints will be sufficient.
User authentication page - Embed this page inside a modal for the client application to retrieve a PlayMetrics User JWT.
auth.gateway..../index.html - Embed the user authentication url into a modal window. Upon successful login the user authentication will emit a PlayMetrics User JWT.
PlayMetrics User JWT - When using the gateway /users/... endpoints, the PlayMetrics User JWT is included in the X-PlayMetrics-User-Token header.