API Token

What is an API token?

An API token is essentially a digital key (a string of characters) that a client application uses to prove its identity and authorisation when communicating with an Application Programming Interface (API). Think of it as a secure pass that verifies who is making a request and what they are allowed to do within the API’s system

Why are API tokens used?

API tokens are employed for several crucial reasons such as;

Enhanced security

API tokens offer stronger security than embedding usernames and passwords in requests. They can be configured to expire after a short period, reducing the risk if intercepted. Additionally, tokens can be restricted in capability—such as being read-only or limited to specific actions—minimising potential damage if compromised.

Granular permissions (scopes)

Tokens can be issued with specific scopes, ensuring that client applications access only the data and actions they require. This supports the principle of least privilege. For example, a photo editing app might be granted access only to a user’s photo library, not their full profile.

Delegated authorisation (OAuth 2.0)

In scenarios where third-party applications need access to user data—such as linking an app to a cloud storage service—API tokens generated via protocols like OAuth 2.0 enable secure delegated authorisation. This allows users to grant limited access to their data without sharing their login credentials.

Machine-to-machine communication

API tokens are well suited for automated interactions between systems, where requiring user involvement for each request is not practical. Services can securely exchange data and perform operations using tokens issued specifically for programmatic access.

Revoking ability

Unlike static credentials, API tokens can be revoked by users or API providers when they are no longer needed or if a security issue arises. This provides better control over access and limits the risk of long-term exposure.

Auditing and tracking

Because tokens can be uniquely linked to specific users or applications, they support detailed logging and monitoring. This makes it easier to trace usage patterns, identify unusual behaviour, and attribute actions to the correct source.

Avoiding exposure of sensitive credentials 

By using tokens instead of usernames and passwords, sensitive information remains protected. Tokens reduce the likelihood of exposing key credentials in transit or logs, lowering the risk of unauthorised access.

How API tokens work

API tokens act like digital keys that allow apps to access certain data or features. Getting and using one usually involves a few steps. Here’s how the process typically works:

– The client requests authorisation: First, the app (known as the client) asks permission from the service it wants to talk to. It sends a request to the service’s authorisation server, saying who it is and what it wants access to—similar to knocking on a door and saying, “Here’s who I am and what I’d like to do.”
– The user consents (potentially): If the request involves user data—like an app wanting to access your photos or contacts—you may be asked to approve it. This is often done through a screen that shows what the app wants to do, giving you the chance to allow or deny access.
– The server verifies credentials: The service then checks if the app is who it says it is, and if you (the user) have given your permission. This step is like the service looking through a guest list to confirm the app’s identity and your approval.
– The authorisation server issues API token: If everything checks out, the service gives the app a token. Think of it like a visitor badge—it shows what areas the app can access and how long it’s valid for. This token is just a string of letters and numbers, but it represents the app’s right to make certain requests.
– The client sends API requests with a token: Now, when the app wants to get or send information, it attaches the token to its requests—like showing its visitor badge at the door each time. This is typically done by including the token in a special part of the request called the Authorisation header.

Authorization: Bearer <your_api_token>

– The server receives and validates the token: The service checks the token to make sure it’s still valid and has permission to do what the app is asking. If the token is fake, expired, or asking for too much access, the request is denied.
– The server processes the request and sends a response: If the token is valid, the service carries out the request (GET, POST, PUT, DELETE, PATCH) and sends a response back to the app.
– The token expiration and renewal: Once a token expires, the client application will need to obtain a new token, usually by repeating a similar authorisation flow or by using a refresh token (if provided during the initial token issuance). Refresh tokens are long-lived tokens used to obtain new access tokens without requiring the user to re-authenticate.

Ready to use API tokens in action? Get a Sportmonks API token and start fetching real-time football data

Types of API tokens

There are several types of API tokens, each designed for specific use cases and security considerations:

Bearer tokens

These are among the most widely used tokens, especially in systems that follow the OAuth 2.0 framework. A bearer token acts like a pass—the client presents it to the server to prove it has access rights. The server doesn’t need to know how the client got the token; it simply checks if the token is valid. Because bearer tokens can be reused by anyone who obtains them, it’s crucial that they’re kept secure and only sent over encrypted connections (such as HTTPS).

API keys

API keys are simpler than bearer tokens. They are usually long strings of characters used to identify which application is making a request. While API keys don’t provide the same level of security as other token types—since they often skip additional verification steps—they’re commonly used for basic APIs or when identifying the developer or project behind a request.

JSON Web tokens (JWTs)

JWTs are a special kind of bearer token. They’re self-contained, meaning they include information about the user or application and their permissions directly within the token. JWTs are digitally signed, allowing the server to confirm that the contents haven’t been tampered with, and that the token is authentic—all without needing to query a database each time.

OAuth 2.0 access tokens

These tokens are issued as part of the OAuth 2.0 authorisation process. They’re short-lived and represent permission granted by a user to an application to access specific resources. For instance, a user might give a calendar app permission to view their events without sharing their login details. The access token contains limits—called scopes—that define exactly what the application can and cannot do.

OAuth 2.0 refresh tokens

Also part of the OAuth 2.0 system, refresh tokens are issued alongside access tokens but are designed to last longer. When an access token expires, the application can use a refresh token to request a new one, without needing to ask the user to log in again. This makes for a smoother experience while still maintaining security.

Session tokens

Although not strictly considered API tokens, session tokens perform a similar role within web applications. When a user logs in, the server generates a token that represents their session and sends it to the browser, typically as a cookie. This token is included in future requests, allowing the server to recognise the user and keep them logged in.

Sportmonks API token

The Sportmonks Football API uses API tokens for authentication and authorisation. These tokens are unique, long-lived strings of characters that identify your application or user account when making requests to our API. Unlike OAuth 2.0 tokens, which may involve complex flows and user consent, Sportmonks API tokens are straightforward and designed for ease of use, making them ideal for developers building applications that require consistent access to football data. You can generate your API token directly from your Sportmonks account at MySportmonks. Each token is tied to your subscription plan, ensuring access to the specific endpoints and data permitted by your plan. For detailed instructions on generating and using API tokens, see our authentication documentation.

Best practices for handling API tokens

Managing API tokens securely is essential to protecting user data and preventing unauthorised access. Whether you’re building an API or using one, following these best practices can help maintain a secure and reliable system.

For API providers

– Use strong token generation: Generate tokens using cryptographically secure methods to ensure they are both unique and hard to guess. This reduces the risk of token duplication or brute-force attacks.
– Implement token expiration: Set a time limit on how long tokens remain valid. If a token is ever compromised, a shorter expiry reduces how long it can be misused.
– Support token revocation: Provide a way for users or administrators to revoke tokens if they are no longer needed or suspected of being compromised. This gives more control over access.
– Use HTTPS for all communication: Always enforce HTTPS for API requests. This encrypts the data—including tokens—while in transit, preventing attackers from intercepting sensitive information.
– Validate tokens on every request: Make sure your server thoroughly checks each token it receives. This includes verifying the token’s signature, expiry time, and permissions before allowing access.
– Store tokens securely: If you store token-related data on your server (such as active tokens or their associated scopes), use secure storage systems and encryption. Avoid saving the full token in a readable format where possible.
– Follow the principle of least privilege: Only grant tokens the exact permissions an application needs—no more. This minimises risk if a token is ever misused.
– Rotate secrets regularly: If your system uses secret keys to sign or verify tokens, make sure to rotate those keys periodically to enhance security.
– Monitor for unusual behaviour: Keep an eye on token usage patterns. Spikes in traffic or unexpected requests could point to a compromised token, allowing you to act quickly.

For API consumers (clients)

– Store tokens safely: Never hardcode tokens directly into your app’s code, especially in places where they might be exposed (e.g. frontend JavaScript). Use secure storage options provided by your platform.
– Use HTTPS for API requests: Ensure that every request you make to an API—including ones that send tokens—uses HTTPS to protect the token while it’s being transmitted.
– Avoid exposing tokens in logs or UI: Don’t log tokens to the console or display them to users. If you need to use them in memory, do so only temporarily and avoid accidental exposure.
– Request only the scopes you need: When requesting access, ask only for the specific permissions your application requires. This limits potential damage if a token is ever compromised.
– Implement token renewal: If you’re using a system with short-lived access tokens and refresh tokens, make sure your application can securely renew access without asking users to log in again.
– Allow users to revoke access: Where possible, let users know how to revoke your app’s access from their account settings on the service you integrate with.
– Raise awareness within your team: Ensure that everyone involved in development understands the importance of proper token handling. A small oversight can lead to major security risks.
– Review permissions regularly: Over time, your app might accumulate permissions it no longer needs. Periodically check and remove any unnecessary access to reduce potential vulnerabilities.

Power your platform with reliable football data

Deliver accurate live scores, detailed player analytics, and comprehensive match data to your users. Sportmonks’ football API offers robust endpoints and extensive coverage to keep your audience engaged. Sign up for a free trial and elevate your sports platform’s performance.