Authentication

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

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.

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:

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

• Resource names — how to address resources once you can reach them.
• Errors and limits — telling an authentication problem from an authorization one.