Identifiers and Keys

Identifiers and Keys

Integrations rely on a small set of identifiers and secret keys that show up across many endpoints. The formatting rules below help integrators catch copy paste errors early and reduce failed requests caused by malformed values.

Identifiers and keys should be treated as opaque strings. Do not infer meaning from their structure.

Identifier formatting

Many Bead objects are referenced by an id value. Examples include:

• merchantId

• terminalId

• applicationId

These identifiers commonly appear in API request bodies and path parameters.

Format

Identifiers use this general format:

• 24 characters

• Hex characters only

• Case-insensitive for format checks

Examples (slightly modified for documentation and not usable as real IDs):

664c5e3b0517b0a8a6321c9b
699764b03b43eb9fd55de045

Recommended format validation

Use this regex to validate identifier formatting:

^[0-9a-fA-F]{24}$

If an identifier does not match this format, return a client-side error before sending the API request, or handle the API response as a validation error.

Format validation only confirms that the identifier is well formed. It does not confirm the identifier exists or that the caller has access to it.

Header keys used to facilitate payments

To initiate a payment request, integrators generally need three pieces of information:

• merchantId

• terminalId

• X-Api-Key header value

The merchantId and terminalId follow the identifier format described above.

The X-Api-Key is a header key that should be treated as a secret. It should never be logged, stored in client-side code, or shared in screenshots.

Terminal X-Api-Key format

A terminal API key commonly uses a three-part, dot-delimited format:

<type>.<encoded-part>.<signature>

Example (slightly modified for documentation and not usable as a real key):

term.Njk5NzY0YjAzYjQzZWI5ZmQ1NWRlMDQ0.CUa6LX8FH-kB1oLQ6C9vKP18VwojKqRqkw0MDU1YsYpxW7J5rMoMYsOPakVT2WCs

Recommended format validation

If you want to do lightweight format validation on the key:

• Must contain exactly 3 segments separated by .

• Segment 1 should be lowercase letters

• Segments 2 and 3 should contain only A–Z, a–z, 0–9, _, -

Regex:

^[a-z]+\.([A-Za-z0-9_-]+)\.([A-Za-z0-9_-]+)$

Format validation does not confirm the key is active or authorized. All real validation happens server-side.

Partner onboarding key formats

Some onboarding and operational workflows may use keys with a similar dot-delimited structure, but with a different prefix and an additional environment marker.

Example (slightly modified for documentation and not usable as a real key):

part.live.Njk2ZTJlM2JkZjBhMDU4ZWRiNTlmN2I3.Jbe4-HDv0FNNXUtpuPhrKM90fsyeQNoXXIduV699VSRRFkdRRa3e1s4SDvF5kkpc

Format

Partner onboarding keys commonly follow this general structure:

<prefix>.<environment>.<encoded-part>.<signature>

Example components:

• Prefix: part

• Environment: live (other environments may exist)

• Encoded part: opaque value

• Signature: opaque value

Recommended format validation

• Must contain exactly 4 segments separated by .

• Segment 1 and 2 should be lowercase letters

• Segments 3 and 4 should contain only A–Z, a–z, 0–9, _, -

Regex:

^[a-z]+\.[a-z]+\.([A-Za-z0-9_-]+)\.([A-Za-z0-9_-]+)$

Security and handling guidance

• Treat all keys as secrets

• Do not log full keys

• Do not commit keys to source control

• Store keys in secure server-side configuration (secrets manager, environment variables)

• Rotate keys immediately if they are exposed

Common validation errors

If you receive a 400-level validation error, check:

• Identifier values are present and match ^[0-9a-fA-F]{24}$

• Keys have the correct number of dot-delimited segments

• No leading or trailing whitespace (copy/paste issues)

• The correct key is being used for the intended environment (test vs live)

If issues persist after confirming formatting, contact Bead Support with the request ID and the relevant entity IDs (do not send full keys in email or chat).