API Authentication and Authorisation

API Authentication and Authorisation

API authentication

API authentication is the process of checking a client’s identity when it makes a request to an API. In other words, it answers the question: “Who is making this request?” This process ensures that only clients with permission can interact with the API, which helps to prevent unauthorised access and misuse of data. Authentication works hand-in-hand with authorisation, which determines the level of access each authenticated client has to different resources or actions.

Why it matters

– Security boundary: Without authentication, an API would accept requests from anyone, including malicious actors. Authentication acts as the first line of defence.
– Foundation for authorisation: Authentication identifies the client, enabling authorisation to decide what actions that client can perform.
– Auditing & monitoring: With an authenticated identity, you can track where requests are coming from, what a user’s patterns are, limit the number of requests per client, and track abuse.
– Granular access control: Some identities may have restricted permissions, such as “read-only match data” or “write team statistics.” This allows for more specific control over what a client can do.

API authorisation

API authorisation is the process of determining what an authenticated client can do once its identity is verified. It answers the question: “What is this client allowed to do?” Authorisation ensures that clients only access data and actions permitted by their role, subscription, or scope.

Why it matters

– Access control: Prevents authenticated users from accessing resources or performing actions outside their permissions.
– Data protection: Ensures sensitive endpoints are only accessible to approved roles.
– Customisation: Allows APIs to tailor responses or limits based on user roles or plans (e.g., read-only vs full access).

Credential / token types

When apps use a protected API, they need credentials or tokens to prove who they are. Here are some common types:

API token / key (static API key)

– Definition: This is a secret string that is given to an app when it registers. It is used to authenticate API calls. The key is included in every request, often in a header or as a query parameter.
– Pros: It is simple to use and has low operational overhead. It works well for basic authentication, especially for server-to-server use in trusted environments.
– Cons / risks: It is a static, long-lived key. If it is ever leaked, it can be misused indefinitely unless it is revoked. It also lacks flexibility, as it doesn’t have a short expiration or a way to delegate specific permissions.
– Use cases: Low-risk endpoints, internal services, or to bootstrap more advanced authentication.

Bearer token (access token style)

– Definition: This is a token, often a JWT or an opaque string, that is passed in requests to prove an app’s identity and its permissions. It is often short-lived, with an expiration time of minutes to hours. The API validates the token by checking its signature, expiry, and permissions.
– Pros: It has stronger security because its short lifespan reduces the window for misuse. It can also contain metadata about the user’s identity and permissions, which allows for more granular access control.
– Cons / challenges: It requires an infrastructure for issuing and validating tokens. You also need to have a way to handle token expiration and revocation.
– Use cases: When you need a way to give specific permissions to each user.

Client ID / secret (client credentials)

– Definition: In OAuth, a client ID (a public identifier) and client secret (a shared secret) are used to authenticate an app with the authorisation server when it requests tokens. It is essentially like a username and password for an app.
– Role: The app uses these during the token exchange.
– Security considerations: The client secret must be stored securely and should not be in public code. For public apps, it is often not used at all.
– Use cases: Server-to-server flows, where the app is trusted to hold secrets securely.

Refresh token

– Definition: This is a longer-lived token that allows an app to get a new access token once the current one expires, without having to ask the user to log in again.
– Lifecycle: When an app first logs in, it gets both an access token and a refresh token. When the access token expires, the app sends a refresh request with the refresh token to get a new access token.
– Pros: It improves usability because the user doesn’t have to repeatedly log in. Access tokens can remain short-lived for safety, while refresh tokens are longer-lived. Using new refresh tokens each time a request is made helps to detect misuse.
– Risks / concerns: A refresh token is very sensitive, as it allows for persistent access. It must be stored securely.
– Use cases: To keep user sessions alive for a long time without repeated login prompts.

Common token passing mechanisms

Authorisation header – bearer / HTTP scheme:

– Description: You pass the token in the Authorization header, often using a Bearer scheme. For example: Authorization: Bearer <access_token>.
– Pros: It’s a clean, standard way of doing things. It keeps the token out of the URL and is widely supported by web frameworks
– Cons / risks: The token still needs to be protected, so you must use TLS/HTTPS to avoid leaks.
– Use cases: This is the default for OAuth 2.0 and is widely considered the best practice for access tokens.

Custom header (e.g., X-API-Key):

– Description: You use a custom HTTP header to send the token or key. For example: X-API-Key: <api_key>.
– Pros: It keeps the token out of the URL and is simple to implement.
– Cons / risks: It’s a less standard approach, so it may require custom code to parse the header.
– Use cases: It’s common for API keys, especially for server-to-server calls.

Query parameter:

– Description: You add the token or key to the end of the URL. For example: GET /matches?access_token=abc123.
– Pros: It’s easy to use in simple clients and works even if HTTP headers have limitations.
– Cons / risks: The token is more exposed. URLs can be logged, stored in browser history, or sent to other websites through a referrer. It should be avoided for sensitive operations.
– Use cases: It is sometimes used for public or read-only endpoints.

– Request body (in payload):

– Description: For POST, PUT, or PATCH requests, you can embed the token as part of the JSON or form body. For example: { “token”: “abc123”, … }.
– Pros: It works when headers are not an option.
– Cons / risks: It’s not a good method for GET requests and is still vulnerable to being logged.
– Use cases: It is less common but sometimes used in custom internal APIs.

Cookies / session cookies:

– Description: You store the token in an HTTP cookie, and the client automatically sends it with every request.
– Pros: It’s useful for websites and automatically includes the token in requests.
– Cons / risks: It can be vulnerable to Cross-Site Request Forgery (CSRF) or cookie theft and is not ideal for third-party APIs.
– Use cases: This is more common in websites with both a user interface and an API.

Token lifecycle & validity

Issuance / minting

A token is generated by the authorisation server after a client has successfully logged in. At this point, the token is given important information like when it’s valid from, when it expires, its permissions, and which client it’s for.

Active / valid state

During its valid period, the token can be used by the client to make calls to protected resources. The server checks the token’s validity, such as its signature and expiration date, on every request. Some tokens are stateless (like a JWT), while others are stateful.

Expiration / expiry

Every token has a set lifespan. Once it reaches its expiration time, it’s no longer accepted. This helps to limit the risk if a token is ever stolen, as an attacker can only use it until it expires. Access tokens typically have a short lifespan, while refresh tokens, if used, last for much longer.

Refresh / renewal

If a refresh token is issued, the client can ask for a new access token without the user having to log in again. Refreshing a token usually checks that the refresh token is still valid. Some systems also use refresh token rotation, where every time a refresh token is used, the server issues a new one and revokes the old one. This makes it harder for an attacker to misuse a stolen token.

Revocation / invalidation

Revocation is when a token is explicitly made invalid before its natural expiration time. This is done for security reasons, such as when a user logs out, a credential is compromised, or a user’s permissions are changed. For stateless tokens, revocation is more challenging. It is often handled by a system that maintains a list of tokens that have been revoked.

Grace / leeway (clock skew handling)

To account for small time differences between a client and a server, servers will often accept a small margin (e.g., a few minutes) when checking a token’s expiration time. However, this leeway should be kept to a minimum to reduce any security risks.

Token binding / constraining

To further reduce misuse, a token can be linked to a specific client, device, or session. This means that even if a token is stolen, it cannot be used elsewhere.

Security best practices

Here are some recommended practices to make your API authentication and token systems more secure. These tips will help reduce risks, prevent misuse, and ensure your system is robust.

1. Always use TLS / HTTPS
Encrypt all communication between the client and the server using TLS/HTTPS. Never accept tokens or credentials over an unencrypted connection. Use strong security settings and enforce HTTP Strict Transport Security (HSTS). Also, ensure that even internal server-to-server calls are encrypted.

2. Use short-lived access tokens & refresh tokens
Access tokens should only be valid for a short time, for example, a few minutes to a few hours. This limits the risk if a token is stolen. You should use refresh tokens, with the right protections, to renew access tokens. This means clients don’t have to frequently re-authenticate. You should also consider rotating refresh tokens, which means issuing a new one and invalidating the old one to reduce the risk of misuse.

3. Enforce the principle of least privilege & scoped access
Tokens or API keys should only grant the smallest amount of permissions needed. Avoid giving “super user” or “global” permissions unless it is absolutely necessary. You should also regularly review the permissions that are granted and adjust them as needed.

4. Secure storage & transmission of credentials / tokens
Never put secrets, such as client secrets, API keys, or refresh tokens, directly into your code. Store them in secure vaults or secret stores. Avoid putting tokens or credentials in URLs, as they can be logged or exposed. Also, avoid logging tokens or secrets by mistake in logs or error messages. On clients like web browsers or mobile apps, use secure storage like HTTP-only cookies or encrypted keystores.

5. Implement token revocation / introspection
You should have a way to invalidate tokens before their natural expiration. This is important when a user logs out, or if there is a suspected security breach. For stateless tokens, you can keep a list of revoked tokens to make sure they are rejected.

6. Use token binding or proof-of-possession
To reduce the risk of token misuse, you can link a token to a specific client, device, or session. This means that even if a token is stolen, it cannot be used elsewhere.

7. Validate claims / metadata in tokens strictly
For tokens with claims, you should validate the signature, the issuer and audience, the expiration time, and the permissions. You should reject any tokens that fail any of these checks.

8. Use an API gateway or middleware
Gateways can centralise security concerns such as authentication, authorisation, and rate limiting. You can offload token validation and other security checks to a gateway rather than having to duplicate them in every service.

9. Rate limiting, quotas & throttling
You should enforce usage limits per client or token to avoid abuse or denial-of-service (DoS) attacks. For example, you can set a limit on the number of requests per minute. You should also have monitoring and alerts for when these limits are reached.

10. Monitor, log & analyse authentication events
Log all key events, such as token issuance, refresh, and unsuccessful attempts. Use anomaly detection to find unusual behaviour, such as many refresh attempts or requests from different geographic locations.

11. Secure design & hardening practices
Adopt a “secure-by-design” approach. This includes conducting security reviews and audits. Use proven libraries and frameworks for authentication and keep them up to date. You should also disable debug and admin endpoints in production or restrict them strongly.

12. Use strong algorithms & key management
You should use secure, modern algorithms for token signing. You should also rotate your signing keys periodically and make sure they are stored securely. You can also version tokens so that tokens signed with old keys can be invalidated.

How Sportmonks implements API authentication and authorisation

Token creation & management

You can create and manage your API tokens in the MySportmonks dashboard. When you create a token, you give it a name, and the system issues it instantly. The token is shown only once at creation, so you must save it somewhere secure. Tokens do not expire automatically; they remain valid until you manually delete them.

Where to place the token (supported methods)

Sportmonks allows two ways to pass the token in API requests:
– Query parameter: Include api_token=YOUR_TOKEN in the URL’s query string.
– HTTP authorisation header: Set Authorization: YOUR_TOKEN in the HTTP headers. You can use either of these methods; they both count towards the same rate limit.

Rate limits & enforcement

Authorisation in Sportmonks APIs is determined by your plan or subscription level. Even with a valid token, access to certain data endpoints or features may be restricted based on your plan permissions.

For instance, a lower-tier plan may have access to live scores but not advanced statistics, while a higher-tier plan unlocks both.

Error codes & handling

When authentication or authorisation fails, Sportmonks returns standard HTTP status codes:
– 401 Unauthorized: This means your token is missing or invalid.
– 403 Forbidden: Your token is valid, but you do not have permission under your plan to access the requested data. This reflects authorisation failure rather than authentication failure.
– 429 Too many requests: You have exceeded your plan’s rate limit.
– 400 Bad request: Your request was not formatted correctly.
– 500 Internal server error: There was a problem on the server’s side.

Security recommendations / notes

– Do not put your API token in client-side code (in a web browser or mobile app). It could be exposed to others.
– You should use a backend or proxy to handle requests. This keeps your tokens safe.
– Always use HTTPS so that your tokens are encrypted while they are being sent.
– Since tokens don’t expire automatically, you should monitor for any misuse and revoke tokens if you think they have been compromised.

Secure your football data access with Sportmonks

Keep your football data safe and reliable with Sportmonks’ API authentication and authorisation. Each API token ensures that only authorised users can access Sportmonks’ Football API, protecting your data from misuse and unauthorised access. Pass your token securely via query parameter or header, and monitor rate limits directly through API responses. Start your free trial with the Sportmonks Football API and explore authenticated, secure access to world-class football data.