> For the complete documentation index, see [llms.txt](https://developers.bead.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.bead.xyz/reference-guide/conventions/identifiers-and-keys.md). # 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: ```regex ^[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: ``` .. ``` 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: ```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: ``` ... ``` 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: ```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). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://developers.bead.xyz/reference-guide/conventions/identifiers-and-keys.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.