Authentication

You'll need to authenticate your requests to access any of the endpoints in the Swypex Partner API. In this guide, we'll look at how authentication works using OAuth 2.0 with Client Credentials Flow.

OAuth 2.0 Client Credentials

The Swypex Partner API uses OAuth 2.0 Client Credentials Flow for server-to-server authentication. This is the recommended and only supported authentication method.

Getting your credentials

To get started, you'll need to request API credentials from your Swypex representative. You'll receive:

Client ID: Your unique client identifier
Client Secret: Your secret key (keep this secure!).

Note that once provided, the Client Secret cannot be retrieved again. Swypex does not store the non-hashed secret and cannot recover it for you. However, you can always generate a new Client Secret if needed.

Token endpoints

The API uses the following OAuth 2.0 endpoints:

Token URL: https://p.swypex.com/v1/oauth/token

Scopes

The API supports the following scopes:

cards:read - Read access to card information (list cards, retrieve card details)
cards:write - Write access to modify card settings (update spending limits)

All endpoints require at least the cards:read scope. Write operations (PUT/PATCH) require the cards:write scope.

Obtaining an access token

To authenticate, you'll need to exchange your client credentials for an access token:

curl -X POST https://p.swypex.com/v1/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id={your_client_id}" \
  -d "client_secret={your_client_secret}" \
  -d "scope=cards:read cards:write"

The response will include an access token.

Token response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "cards:read cards:write"
}

The expiration time (expires_in) is given in seconds. After this time, you'll need to request a new access token.

Making authenticated requests

Once you have an access token, include it in the Authorization header of your API requests:

GET

/v1/card

curl -G https://p.swypex.com/v1/card \
  -H "Authorization: Bearer {access_token}" \
  -d limit=10

Token expiration and refresh

Access tokens are valid for the duration specified in the expires_in field (typically 1 hour). When your token expires, you'll need to request a new one using the same client credentials flow shown above.

The API will return a 401 Unauthorized response when your token is invalid or expired:

Unauthorized response

{
  "message": "Invalid or expired token",
  "type": "InvalidRequest"
}

Suggested Security best practices

Always keep your client credentials secure and never commit them to version control.

Store your client secret securely (use environment variables or a secrets manager.)
Never expose your client credentials in client-side code.
Rotate your credentials periodically. Swypex will try to remind you to do so every quarter days. But you can rotate them anytime via your Swypex representative.
Use the minimum required scopes for your application.
Monitor your API usage for suspicious activity.
Implement proper error handling for authentication failures.