Authentication and environments

Keep uses OAuth 2.0. You authenticate with the Client Credentials flow, which is designed for server-to-server communication where no user interaction is required. This authorization layer protects your data on the Keep domain against unauthorized access and mutation.


Before you start: your credentials

Before starting integration you must receive your Partner API keys from your Account Manager:

PayMe gives you your partner domain together with these credentials (see Base URL).

Your API keys carry many privileges, so keep them secure. Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth. You send them only to the Obtain access token endpoint, which exchanges them for the access and refresh tokens you use everywhere else.


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.

Environment Server
Sandbox https://<partner_domain>.keep.co.il — your partner domain on the Keep sandbox
Production https://<partner_domain>.keep.co.il — your partner domain

Paths start with /oauth2/token, /api/public/..., /partner/api/... and /seller/api/....

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.


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

Refresh Token


Scopes

Scopes define what resources and actions your integration can access.

Scope Description
partner-api Access to partner-level endpoints and resources: the Partner API
seller-api Access to seller-level endpoints and resources: the Seller API

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


Token requests

  1. POST /oauth2/token with application/x-www-form-urlencoded body: grant_type=client_credentials, client_id, client_secret, scope. Always request the scope for the API you are calling: partner-api for the Partner API, seller-api for the Seller API. A token without the required scope is refused with 403 by the endpoints that require it. 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. Refreshing also ends the previous access token at once, so switch to the new access token immediately. If a refresh is refused with 400 invalid_request (Invalid refresh token), request a new token with your client credentials.

What the token endpoint returns when a request fails is on Errors.


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 your Account Manager 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. Then read Errors.