Authorization Flow

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.

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.
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; the full request and response formats are on Obtain access token.