Create an API key
In the Emporix Developer Portal, open Manage API Keys and create a custom key with only the scopes of the commands you run. Each command’s help ends with the scopes it requests, as does its entry in the CLI reference:product.product_manage, only to keys that send
writes. Keep them off keys you use only to read.
Set environment variables
When a required setting is missing, any command that calls Emporix, and any write’s
--dry-run, fails with exit code 2 and names what to set.
Store keys in profiles
A profile keeps an API key so you can switch between tenants and keys without exporting variables. It holds a tenant, an API URL, a client ID, and optionally a default site and language. The client secret goes to your OS keychain, never to a file.profile add asks for the client secret on a terminal without showing it. Elsewhere, it
reads the first line of standard input:
profile add sends nothing to Emporix;
check the new key with epx --profile dev auth status.
Choose a profile
A command uses the profile that--profile names, then the one in EPX_PROFILE, then
the default profile. Profiles apply only when no EMPORIX_ variable is set: the
environment or a profile supplies the whole API key, never a mix of both, so a client
secret only ever goes to its own API URL. Naming a profile while an EMPORIX_ variable
is set is a usage error.
A profile’s default site and language apply on its own tenant to commands that need a
site or show translations, when you don’t pass --site or --language.
Where profiles are stored
Profile names have up to 64 characters: lowercase letters and digits, with
., _,
and - after the first. The Windows Credential Manager ignores case, so Dev and dev would share a
secret.
Check your API key
auth status requests a token for your tenant and each --scope, then shows the tenant,
the token’s lifetime, and the scopes granted. It never prints the token. Emporix only
grants the scopes a token asks for, so pass every scope you want to check.
Missing scopes
Emporix doesn’t reject a token request for a scope your API key lacks. It leaves the scope out of the token, and reads may then return less data, such as published products only. To keep that from going unnoticed, epx compares every token with the scopes and tenant it asked for, and fails with exit code 3 when one doesn’t match:Write-capable scopes for reads
A few reads are allowed by Emporix only with a scope that can also change data, such assite.site_manage. epx treats any scope whose name doesn’t contain read or view as a
word as write-capable. These reads request such a scope only when you pass
--allow-write-scope, and their help marks them as opt-in:
--scope.
Global flags
These flags apply to every command:
Once you’ve set up a key, take the quickstart or read the
security model.