• Request
• Response
• Payload examples

Request

Endpoints

Required Keys

Body

📌

Send overwriteExistingKey on every request

Send true or false explicitly so the outcome for a merchant that already has credentials is the one you intend. When the merchant has no credentials yet, both values create a new key.

Response

A successful request returns 201 Created with the credentials.

Field Definitions

❗️

Security for appSecret

Store the appSecret securely and share it only with the merchant it belongs to. Anyone holding the appKey and appSecret can authenticate as that merchant.

HTTP status codes

Payload Examples

Request

cURL Request Example

curl --request POST \
     --url https://api-sandbox.flexfactor.io/v1/merchants/{mid}/api-keys \
     --header 'Authorization: Bearer {the token returned by /oauth2}' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
       "name": "My API Key",
       "description": "Key for the merchant integration",
       "overwriteExistingKey": false
     }'

Response

JSON Example for a Successful Creation

{
   "name": "My API Key",
   "uniqueName": "My API Key",
   "description": "Key for the merchant integration",
   "clientId": "{{$guid}}",
   "appKey": "{appKey}",
   "appSecret": "{appSecret}"
}

Example for Handling Errors

• Missing Fields: If a required field is missing, the API returns a 400 error with validation problem details.
• Invalid Credentials: If the bearer token is missing, invalid, or expired, the API returns a 401 error with an empty body.
• Merchant not in your account: If the merchant does not belong to your partner account, the API returns a 401 error with a message.

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "Name": [
      "The Name field is required."
    ]
  }
}

HTTP/1.1 401 Unauthorized

Access denied: Merchant does not belong to your partner account