Authorization Flow

This document provides a high-level overview of the Keep API authentication system.

Authorization Overview

This document provides a high-level overview of the Keep API authentication system.

---

Introduction

The PayMe API uses OAuth 2.0 for secure authentication. API integrators authenticate using the Client Credentials flow, which is designed for server-to-server communication where no user interaction is required.

---

How It Works

Authentication Flow

1. Your server requests an access token using your client credentials
2. The API returns an access token and refresh token
3. Use the access token to make authorized API requests
4. When the access token expires, use the refresh token to obtain a new one
5. When the refresh token expires, repeat from step 1

---

Authentication Methods

Client Credentials

This is the primary authentication method for API integrators. Your server authenticates directly with the PayMe API using a client ID and client secret provided during onboarding.

When to use: Server-to-server integrations, backend services, automated processes

Refresh Token

Used to obtain a new access token without re-authenticating with credentials. This ensures continuous API access without storing sensitive credentials for repeated use.

When to use: When your current access token has expired or is about to expire

---

Tokens

Access Token

• Used to authenticate API requests
• Short-lived (typically 1 hour)
• Must be included in the Authorization header of every API request
• Format: Bearer <token>

Refresh Token

• Used to obtain new access tokens
• Long-lived (typically 30 days)
• Should be stored securely
• Cannot be used to make API requests directly

---

Scopes

Scopes define what resources and actions your integration can access.

Scope	Description
partner-api	Access to partner-level endpoints and resources
seller-api	Access to seller-level endpoints and resources

Request only the scopes your integration needs to follow the principle of least privilege.

---

Security Considerations

Important Security Practices

• Never expose your client secret in client-side code
• Always use HTTPS for all API communications
• Store tokens securely using encryption
• Implement token refresh before expiration
• Rotate credentials periodically

---

Getting Started

1. Obtain Credentials - Contact Keep to receive your client_id and client_secret
2. Request Access Token - Use the Client Credentials flow to obtain tokens
3. Make API Requests - Include the access token in your API calls
4. Handle Token Refresh - Implement logic to refresh tokens before they expire

---

Next Steps

For detailed implementation instructions including request/response formats and code examples, see the Authorization Flow documentation.