Skip to content

Service accounts

A service account is a special kind of account that can be used by an application instead of a person. Applications use service accounts to make authorized API calls to Enfonica.

There are two kinds of service account:

  • A project's service account works in one project. Use it for an app that needs only that project.
  • An organisation's service account works across every project in your organisation, including projects that are created later. Use it for an app that manages many projects, such as one that creates a project for each of your customers. Only an owner of the organisation can create one.

To use a service account with the Enfonica API, you must download the service account key, which is a JSON file containing authentication details. Both kinds of key work the same way in your app. To use the key, see Authentication.

Create a project's service account

A project's service account can be granted IAM roles in the same way that user accounts can. It's identified by its email address, SERVICE_ACCOUNT_ID@PROJECT_ID.iam.enfonica.com, which is unique to the project.

To create a project's service account:

  1. In the Enfonica Console, open the project that you want to use, and go to Settings > Service accounts.

    Open Enfonica Console

  2. Select Create service account.

  3. Enter a Service account ID of 6 to 30 lowercase letters, digits, and hyphens. You can also enter a Description.
  4. Select a Role, and then select Create. Give the service account the least access that your app needs. Custom roles grants Viewer or Editor access one product at a time.
  5. On the new service account's page, under Keys, select Add key, and then select Create and download key. A JSON key file downloads.

You can't download the key file again, and anyone who has it can act as the service account. Store the key file in a safe location, and keep it out of your source code.

To delete a key, open its menu under Keys, and select Delete key.

Create an organisation's service account

An organisation's service account has one role, which applies to every project in your organisation. It's identified by its email address, SERVICE_ACCOUNT_ID@ORGANISATION_ID.tenants.iam.enfonica.com.

To create an organisation's service account, you must be an owner of the organisation:

  1. In the Enfonica Console, at the top of the sidebar, select Back to projects to open your organisation's pages, and then select Service accounts.
  2. Select Create service account.
  3. Enter a Service account ID of 6 to 30 lowercase letters, digits, and hyphens, starting with a letter. You can also enter a Description (optional).
  4. Select a Role, and then select Create. Give the service account the least access that your app needs:
    • Owner: full access to every project.
    • Editor: edit access to every project, and can create projects.
    • Viewer: view access to every project.
  5. On the new service account's page, under Keys, select Add key, and then select Create and download key. A JSON key file downloads.

You can't download the key file again, and anyone who has it can act as the service account in every project in your organisation. Store the key file in a safe location, and keep it out of your source code.

In the key file, project_id is -, which means any project, because the key isn't for one project. The code samples and the Enfonica client libraries use the key file as it is.

What an organisation's service account can't do

So that a leaked key can't be used to create more keys or give anyone more access, an organisation's service account doesn't get these parts of its role in your projects:

  • Create, change, or delete service accounts, or create or delete their keys.
  • Change who has access to a project.
  • Read or renew a project's request signing key.
  • Manage your organisation's users and invitations.

The service account becomes the owner of each project that it creates, so it has full access to those projects, including who has access to them. Creating a project needs the Owner or Editor role.

Change or delete an organisation's service account

On the service account's page, you can change its Description and Role, and then select Save Changes. A new role applies from the service account's next access token. Access tokens that were already issued keep the old role until they expire, which is within an hour.

To delete a key, open its menu under Keys, and select Delete key. To delete the service account and all of its keys, open the menu at the top of the page, and select Delete service account. Access tokens that were already issued keep working until they expire, which is within an hour.