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!).

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)
• transfers:read - Read access to transfer information
• transfers:write - Write access to create and manage transfers

The current OpenAPI specification requires all four scopes on card endpoints. Request tokens with cards:read cards:write transfers:read transfers:write unless you have been told otherwise by the Swypex team.

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 transfers:read transfers:write"

The response will include an access token.

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

Making authenticated requests

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

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

Signed write requests

Read requests only need the Authorization header. Card write requests such as PUT /v1/card/:id/limits and PATCH /v1/card/:id/limits must also include three additional headers:

For example, when calling PUT /v1/card/CRD1000000000/limits, sign the string PUT/v1/card/CRD1000000000/limits1699012345 with your private RSA key using SHA-256, then Base64-encode the resulting signature.

curl -X PATCH https://p.swypex.com/v1/card/CRD1000000000/limits \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/merge-patch+json" \
  -H "Idempotency-Key: 7d75ad92-6f8d-421f-8c21-4c1d208d81b0" \
  -H "X-Swypex-Request-Timestamp: 1699012345" \
  -H "X-Swypex-Signature: {base64_rsa_sha256_signature}" \
  -d '{"daily": 1000000}'

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:

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

Suggested Security best practices

• 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.