API keys

#API keys

sdk.apiKeys manages machine credentials. A key acts as a user with a fixed role; optional scopes narrow (never widen) what that role can do — the effective permission is always role ∩ scopes.

#Create a key

The raw key is returned once on creation — store it immediately.

const created = await sdk.apiKeys.create({
	name: 'ci-importer',
	role: 'editor',
	// Optional: narrow the role to specific resources/actions
	scopes: ['collections/products:read', 'collections/products:create']
});

console.log(created.key); // 'sk-…' — shown only this once

#List, inspect, update, revoke

const keys = await sdk.apiKeys.list(); // summaries — never the raw key

// What can this key actually do? (role ∩ scopes, resolved server-side)
const perms = await sdk.apiKeys.permissions(keys[0].id);

await sdk.apiKeys.update(keys[0].id, { name: 'ci-importer (staging)' });
await sdk.apiKeys.revoke(keys[0].id);

#Using a key

Pass the key as the SDK's token — requests authenticate with Authorization: Bearer sk-…:

const sdk = new EmuView({ url: 'https://api.example.com', token: 'sk-…' });

#What you learned

• create() returns the raw sk- key exactly once
• Scopes only narrow the key's role; permissions(id) shows the effective set
• Revoked keys are rejected within the session-cache TTL