# Authorization Flow

Building with an AI agent? Start at https://docs.payme.io/agents.md

How Keep API authentication works: OAuth 2.0 client credentials, the token request and refresh, access and refresh tokens, scopes, the base URL on your partner domain, and security practices.

# 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. Use the lifetime returned in `expires_in`
- Must be included in the `Authorization` header of every API request
- Format: `Bearer <token>`

### Refresh Token

- Used to obtain new access tokens
- When supplied, `refresh_expires_in` gives the refresh-token lifetime
- 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.

---

## Base URL

Keep is served on your partner domain, `https://<partner_domain>.keep.co.il`, in both environments; PayMe gives you the domain together with your Keep credentials. Paths start with `/oauth2/token`, `/api/public/...`, `/partner/api/...` and `/seller/api/...`. 

---

## Token requests

1. `POST /oauth2/token` with `application/x-www-form-urlencoded` body: `grant_type=client_credentials`, `client_id`, `client_secret`, `scope` — `partner-api` for the Partners API, `seller-api` for the Seller API. The field is optional in the request, but a token issued without a scope is refused with `403` by every Keep endpoint. Endpoint reference: [Obtain access token](/keep/partners-api/gettoken).
2. The response has `access_token`, `refresh_token`, `expires_in`, `token_type`. `refresh_expires_in` is included when supplied. `scope` is included when the issued token has a non-empty scope.
3. Send `Authorization: Bearer <access_token>` on every request.
4. Refresh with `grant_type=refresh_token` and the `refresh_token`. A refresh token works once: the response carries a new one, and the new token keeps the scopes of the original.

All requests must use HTTPS; plain HTTP and unauthenticated calls fail. 

---

## 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
> - Credentials are issued by your Account Manager and cannot be rotated or regenerated by you. If you believe a secret has leaked, contact your Account Manager. 

---

## 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

The token requests are listed in [Token requests](#token-requests); the full request and response formats are on [Obtain access token](/keep/partners-api/gettoken).