Authentication and environments
Related
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:
Client IDClient Secret
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
- Your server requests an access token using your client credentials
- The API returns an access token and refresh token
- Use the access token to make authorized API requests
- When the access token expires, use the refresh token to obtain a new one
- 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
Authorizationheader of every API request - Format:
Bearer <token>
Refresh Token
- Used to obtain new access tokens
- When supplied,
refresh_expires_ingives 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: 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
POST /oauth2/tokenwithapplication/x-www-form-urlencodedbody:grant_type=client_credentials,client_id,client_secret,scope. Always request the scope for the API you are calling:partner-apifor the Partner API,seller-apifor the Seller API. A token without the required scope is refused with403by the endpoints that require it. Endpoint reference: Obtain access token.- The response has
access_token,refresh_token,expires_in,token_type.refresh_expires_inis included when supplied.scopeis included when the issued token has a non-empty scope. - Send
Authorization: Bearer <access_token>on every request. - Refresh with
grant_type=refresh_tokenand therefresh_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 with400invalid_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
- Obtain Credentials - Contact your Account Manager to receive your
client_idandclient_secret - Request Access Token - Use the Client Credentials flow to obtain tokens
- Make API Requests - Include the access token in your API calls
- 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.