Authentication

Service accounts, key types, and how to hold credentials safely.

Every call to SPEKTRA Edge is made by a principal — a specific identity the platform can name, and whose access it can evaluate. Getting automation right is mostly a matter of choosing the right kind of principal and then keeping its credentials somewhere sensible.

Who your code should be

Principal Created for Use for automation?
User A human, backed by the identity provider. No. Tied to a person who may change roles or leave.
Service account A workload. Belongs to a project, in a region. Yes. This is the intended identity for automation.
Group A set of users or service accounts, addressed by one email. Useful for granting access to several principals at once, not as a caller.

A service account is regional, and its name reflects that:

projects/{project}/regions/{region}/serviceAccounts/{serviceAccount}

It also has an email-style identifier, which is what role bindings refer to:

{serviceAccount}@{project}.{region}.serviceaccounts.iam.edgelq.com

Create one per job instead of one shared “automation” account — see Service accounts for why, and for how the account model works in general.

Key types

A service account is an identity; a key is how a caller proves it holds that identity. Choose the algorithm when you create the key.

Algorithm What you get Suits
API_KEY A single bearer token. Shell scripts, CI jobs, REST calls, quick tooling.
RSA_2048 An RSA keypair; the private key is returned to you. gRPC clients and long-running services. RSA_1024 and RSA_4096 are also accepted. 
cuttle iam create service-account-key api-key \
  --parent projects/$PROJECT/regions/$REGION/serviceAccounts/automation \
  --algorithm API_KEY \
  -o json

You can also bound a key in time with validNotBefore and validNotAfter, which is the cleanest way to guarantee a credential issued for a short-lived job cannot outlive it.

Presenting a credential

REST and gRPC-Web take an API key as a bearer token:

Authorization: Bearer {API_KEY}

gRPC clients normally use a service account key file instead. This is the same JSON format cuttle stores, so the SDK clients can consume the file that cuttle iam create service-account-key writes without conversion. The device agent uses the same mechanism, which is why a device’s credentials look like a service account key on disk — because that is what they are.

Granting access

Authenticating tells the platform who you are; it grants nothing on its own. A new service account can make calls and will be denied all of them until a role binding gives it a role in a scope.

cuttle iam create role-binding automation-viewer \
  --parent projects/$PROJECT \
  --member "serviceAccount:automation@$PROJECT.$REGION.serviceaccounts.iam.edgelq.com" \
  --role "services/iam.edgelq.com/roles/viewer"

Three parts matter, and each is a common source of confusion.

The member string is typed. The prefix is part of the value:

Member Meaning
user:{email} One human.
serviceAccount:{email} One service account.
group:{email} Everyone in a group.
domain:{domain} Anyone with an identity in that domain.
allAuthenticatedUsers Any authenticated principal.
allUsers Anyone at all, including unauthenticated callers.

The last two deserve care: they are how genuinely public resources are exposed, and almost never what you want for automation.

The scope is the --parent. A role binding applies at an organization, a project, or a service, and inherits downwards only. Granting a role on a project grants nothing on its parent organization or on a sibling project. See Accounts & access for the full model.

Bindings settle asynchronously. A platform controller applies them, so expect up to a minute or two before a new binding takes effect. Treat an immediate PERMISSION_DENIED after granting access as “not yet”.

Restricting where a credential works

A role binding can carry conditions that constrain it beyond the role and scope; an IP condition is the most useful for automation. See Service accounts.

Holding credentials safely

Keys are additive, so rotation needs no downtime, and the storage rules are the same whether a key is used from CI or from a long-running service. Service accounts covers both, along with where not to put key material.

One point is specific to writing code against the API: the credential your automation uses to call SPEKTRA Edge is a different thing from the values your workloads need at runtime. For registry credentials and application configuration, use the secrets service instead of baking them into an image.

Next steps