Service Principals

Professional Edition Administrators can use service principals in Wherobots Cloud. Service principals enable authentication to APIs through long-lived tokens.

Administrators can create and manage tokens for applications and services, eliminating the need for User(1) role members within your Organization to handle API keys. This detaches authentication from an individual User, improving security and simplifying API access management.

1. In Wherobots Cloud, the Admin role has higher privileges and authority than the User role.

Service principals can enable the usage of Wherobots APIs including the Spatial SQL API, CI/CD pipelines, and automated workflows like Apache Airflow ETLs.

Before you start

In order to use service principals, ensure that you have the following:

• A Wherobots Professional or Enterprise Edition Organization. Only Professional or Enterprise Edition Organizations can use service principals.
  • For more information on paid plans, see Wherobots Pricing.
    • To create a new Professional Edition Organization, see Create a Professional Edition Organization.
    • To upgrade your Community Edition Organization to a Professional Edition Organization, see Upgrade Organization.
    • To create a new Enterprise Edition Organization, see Create an Enterprise Edition Organization.
• An Admin role within your Organization.
  • To confirm that you're an Administrator, review your role in Organization Settings > Users.
  • Those with a User role can't manage service principals or their associated API keys.
    • While Organization Administrators can give those in the User role access to the API keys associated with a service principal, those in a User role cannot create, modify, or delete service principals or their related API keys.

Use service principals as an Administrator

Administrators have the ability to create, modify, or delete service principals.

Create a service principal

To create a service principal, do the following:

1. Login to your Professional or Enterprise Edition Wherobots Organization.
2. Go to Organization Settings > Users.
3. Scroll to Service Principals.
4. Click Create Service Principal.
5. Assign a Name to your service principal. Your service principal's name can only include alphanumeric characters.
6. Click Submit.

When you successfully create a service principal, you will be redirected to your service principal's detail page.

Manage a service principal

As an Administrator, you can:

• Rename a service principal
• Assign API keys to a service principal
• Delete a service principal

Find your service principal

To modify your service principal first find your service principal by doing the following:

1. Login to your Professional or Enterprise Edition Wherobots Organization.
2. Go to Organization Settings > Users.
3. Scroll to Service Principals.
4. Click the service principal that you want to modify. You will be taken to that service principal's detail page.

Rename service principal

To change the name of your service principal, do the following:

1. Follow the steps in Find your service principal.
2. Edit the Name field.
3. Click Save.

Add an API key to a service principal

1. Follow the steps in Find your service principal.
2. Scroll to API keys.
3. Click Create New Key.
4. Enter a value in the Name field.
5. Choose an Expiration Date for your API key. This value defaults to 1 year from when the API key is created.
6. Click Submit.

After clicking Submit, Wherobots generates an API key.

Note

Copy and store your API key securely, as Wherobots will not show you this API key again.

Delete a service principal

As an Administrator, you can delete a service principal. Deleting a service principal also revokes the API keys associated with that service principal.

To delete a service principal, do the following:

1. Follow the steps in Find your service principal.
2. Review the service principal's associated API keys. Deleting the service principal will also revoke its API keys.
3. Click Delete service principal.
4. When asked to confirm if you want to delete the service principal, click Delete.

Access API keys from an Admin

If you're configured as a User in your Organization, you won't be able to view or manage API keys or service principals in your Organization.

In order to gain access to any needed API keys, an Admin from your Organization must share the necessary credentials with you.

Contact your Wherobots Organization Administrator if you have further questions regarding your Organization's service principals or API keys.

To find the Admin associated with your Organization, do the following:

1. Go to Organization Settings > Users.
2. Find the email address associated with the Admin in your Organization.

Switching to service principal-managed API keys

Existing API keys that are not already associated with a service principal cannot be migrated to one. Instead, you'll need to create new API keys under a service principal.

If you want to use service principal-managed API keys instead of unattached API keys, do the following:

1. Manually revoke those initial API keys from your Organization.
   1. Log in to your Wherobots Organization.
   2. Go to Organization Settings > Security.
   3. Find API Keys section.
   4. Locate the Owned by column.
   5. Identify API keys owned by individuals rather than a service principal.
   6. Scroll to the right and click ... > Revoke.
   7. Click Revoke to confirm that you want to remove this API key from your Organization.
2. Create a new service principal.
3. Add an API key to that service principal.