passbolt/passbolt_api · error · BadRequestException

The metadata key identifier should be a UUID.

Error message

The metadata key identifier should be a UUID.

What it means

Format guard when sharing a metadata key with a user: the id route parameter (the metadata key id) fails Validation::uuid(), so the request is rejected with 400 before the private key creation service is called.

Solutions

1. Use the metadata key UUID from GET /metadata/keys in the path.
2. Fix URL template interpolation so the id resolves.
3. Validate the id with a UUID regex before calling.

Example fix

// before
post(`/metadata/private/${fingerprint}/private-keys`, body);
// after
post(`/metadata/private/${metadataKeyId}/private-keys`, body); // metadataKeyId is a UUID

if (!isUuid(metadataKeyId)) throw new Error('metadata key id must be a UUID');

const isUuid = (v) => typeof v === 'string' && /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(v);

try { await api.post(`/metadata/private/${metadataKeyId}/private-keys`, body); } catch (e) { if (e.response?.status === 400) { metadataKeyId = (await api.get('/metadata/keys')).find(k => k.fingerprint === fingerprint).id; return retry(); } throw e; }

When it happens

Trigger: Creating a metadata private key where the {metadataKeyId} path segment is not a valid UUID (fingerprint, empty string, numeric id).

Common situations: Using the OpenPGP fingerprint instead of the passbolt metadata key UUID; URL templating that left a placeholder unfilled; ids copied from the wrong entity.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

• The metadata key ID should be a valid UUID.
• The metadata key ID should be a valid UUID.
• The private key identifier should be a UUID.
• Invalid id
• Invalid request. New key or passwords are not required.

AI-assisted analysis of passbolt/passbolt_api@31c1bbc10f (2026-09-17). Data as JSON: /api/errors/6508b8bd7b561bc0. Report an issue: GitHub.

Appendix: source

Thrown at plugins/PassboltCe/Metadata/src/Controller/MetadataPrivateKeysCreateController.php:39

use Cake\Validation\Validation;
use Passbolt\Metadata\Service\MetadataPrivateKeysCreateService;

class MetadataPrivateKeysCreateController extends AppController
{
    /**
     * Share a metadata key with a given user
     *
     * @param string $id metadata key id
     * @return void
     */
    public function create(string $id)
    {
        $this->assertJson();
        $this->assertNotEmptyArrayData();
        $this->User->assertIsAdmin();

        if (!Validation::uuid($id)) {
            throw new BadRequestException(__('The metadata key identifier should be a UUID.'));
        }
        $data = $this->request->getData();

        $created = (new MetadataPrivateKeysCreateService())->create($this->User->getAccessControl(), $id, $data);
        $this->success(__('The operation was successful.'), $created);
    }
}

View on GitHub (pinned to 31c1bbc10f)