API v2.4 documentation for CoastSnap

Get access token

Appendix

Using the SPOTTERON API with Client Credentials Flow

Overview

OAuth 2.0 is an authorization framework that allows applications to obtain limited access to a user’s resources without exposing their credentials. The Client Credentials flow is a specific OAuth 2.0 flow designed for machine-to-machine (M2M) authentication, where the client (app) can access resources on its own behalf rather than on behalf of a user.

Client Credentials are bound to a user account. Currently, clients have all permissions as the user it is bound to. This might be restricted in the future, so a client could have only a subset of the permission given to a user.

Prerequisites

• OAuth2 endpoint details (provided by the API service):
  • Token URL: URL where your application can obtain an access token.
  • Client ID and Client Secret: Credentials provided by the API service for your application.
• API Endpoint URL: URL of the resource you wish to access.

Understanding the Client Credentials Flow

In this flow:

1. Your client (application) authenticates itself with the authorization server by providing the client ID and client secret.
2. The authorization server verifies the credentials and returns an access token.
3. Your client uses this access token to access protected resources on behalf of itself.

Getting Started with the Client Credentials Flow

Step 1: Register Your Application

Contact Spotteron to get a Client ID and Client Secret.

Step 2: Define the Required Parameters

When requesting an access token, you’ll need the following parameters:

• grant_type: Must be set to client_credentials.
• client_id: Your client ID.
• client_secret: Your client secret.

Requesting an Access Token

The access token request is typically made to the Token URL via a POST request. Example Request:

Use a POST request to obtain an access token. Here’s an example using curl:

curl -X POST \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  https://www.spotteron.com/api/v2/access_token

Replace YOUR_CLIENT_ID and YOUR_CLIENT_SECRET with the appropriate values. Note: Always use HTTPS to protect credentials.

Sample Response:

If successful, the authorization server responds with a JSON object containing an access_token, token_type, and sometimes expires_in.

{
  "access_token": "your_access_token_here",
  "token_type": "Bearer",
  "expires_in": 3600
}

• access_token: The token you’ll use to access resources.
• token_type: Typically "Bearer" for OAuth 2.0 tokens.
• expires_in: The lifetime of the token in seconds (e.g., 3600 seconds = 1 hour).

Using the Access Token

Once you have the access token, you can make requests to the API on behalf of your application. Include the access token in the Authorization header of your API requests. Example Request with Access Token:

Use curl to make a request to the API endpoint with the access token:

curl -X GET \
  -H "Authorization: Bearer your_access_token_here" \
  https://www.spotteron.com/resource

Explanation:

• Authorization Header: Include the access token in the Authorization header with the Bearer prefix.
• API Endpoint: Replace https://www.spotteron.com/resource with the actual endpoint you want to access.

Handling Expired Tokens

Access tokens have a limited lifetime (defined by expires_in in the token response). Once the token expires, you’ll need to request a new one using the same client_credentials request flow.

To manage expired tokens:

Track the token's expiry time based on the expires_in value. Re-authenticate (repeat the token request) when the token expires.

Error Handling

The authorization server may return errors if something goes wrong. Common errors include:

• Invalid Client: The client ID or secret is incorrect.
• Unauthorized Client: The client is not allowed to use the requested grant type.

Example Error Response:

Invalid client:

{
  "error":"invalid_client",
  "error_description":"Client authentication failed",
  "message":"Client authentication failed"
}

Tips for Error Handling:

• Check the error and error_description fields in the response.
• Verify your client ID and client secret if you receive invalid_client.
• Ensure the grant_type is client_credentials.

Sample Implementation

Here’s a quick implementation in Python using the requests library to automate the process. Python Example:

import requests

# OAuth2 details
token_url = "https://www.spotteron.com/oauth2/access_token"
client_id = "YOUR_CLIENT_ID"
client_secret = "YOUR_CLIENT_SECRET"

# Request an access token
response = requests.post(
    token_url,
    data={
        "grant_type": "client_credentials",
        "client_id": client_id,
        "client_secret": client_secret
    }
)

# Parse the token response
if response.status_code == 200:
    access_token = response.json().get("access_token")
    print("Access Token:", access_token)

    # Use the access token to access a protected resource
    api_url = "https://www.spotteron.com/resource"
    api_response = requests.get(
        api_url,
        headers={"Authorization": f"Bearer {access_token}"}
    )

    # Print the response from the API
    print("API Response:", api_response.json())
else:
    print("Failed to obtain access token:", response.json())

Security Considerations

• Keep your Client Secret safe: Treat it like a password. Avoid hardcoding it in your codebase if possible, or use secure environment variables.
• Use HTTPS: Always use HTTPS to prevent your credentials and tokens from being exposed in transit.

Summary

• Register your app to get the client ID and client secret.
• Use the Client Credentials flow to request an access token from the token URL.
• Use the access token in the Authorization header when making API requests.
• Refresh the token once it expires.

This manual covers all the steps to authenticate using OAuth 2.0 Client Credentials flow and access protected resources.