# Authentication and environments Building with an AI agent? Start at https://docs.payme.io/agents.md ## Related - [Obtain access token](/keep/authentication/gettoken) - [Errors](/keep/partner-authorization/errors) 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 ID` - `Client Secret` PayMe gives you your partner domain together with these credentials (see [Base URL](#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](/keep/authentication/gettoken) endpoint, which exchanges them for the access and refresh tokens you use everywhere else. --- ## Base URL Keep is served on your partner domain, `https://.keep.co.il`, in both environments; PayMe gives you the domain together with your Keep credentials. | Environment | Server | |-------------|--------| | Sandbox | `https://.keep.co.il` — your partner domain on the Keep sandbox | | Production | `https://.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 - 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 ` ### 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: the [Partner API](/keep/partner-api) | | `seller-api` | Access to seller-level endpoints and resources: the [Seller API](/keep/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](/keep/authentication/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 ` 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](/keep/partner-authorization/errors#token-endpoint-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](#token-requests); the full request and response formats are on [Obtain access token](/keep/authentication/gettoken). Then read [Errors](/keep/partner-authorization/errors).