> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wherobots.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Service Principals

> Professional Edition Administrators can create and manage 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** role members within your Organization to handle API keys. This detaches authentication from an individual **User**, improving security and simplifying API access management.

Service principals can enable the usage of Wherobots APIs including the [Spatial SQL API](/develop/spatial-sql-api), CI/CD pipelines, and automated workflows like [Apache Airflow ETLs](/develop/airflow-provider).

## 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](https://wherobots.com/pricing/).
    * To create a new Professional Edition Organization, see [Create a Professional Edition Organization](/get-started/wherobots-cloud/create-account/#create-a-professional-edition-organization).
    * To upgrade your Community Edition Organization to a Professional Edition Organization, see [Upgrade Organization](/get-started/upgrade-organization/).
    * To create a new Enterprise Edition Organization, see [Create an Enterprise Edition Organization](/get-started/wherobots-cloud/create-account/#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**](https://cloud.wherobots.com/organization#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:

<Steps>
  <Step>
    Login to your Professional or Enterprise Edition [Wherobots Organization](https://cloud.wherobots.com/).
  </Step>

  <Step>
    Go to [**Organization Settings > Service Principals**](https://cloud.wherobots.com/organization#service-principals).
  </Step>

  <Step>
    Click **Create Service Principal**.

    <Frame>
      <img src="https://mintcdn.com/wherobots/GrWfTlqud5HZFYRl/images/get-started/service-principals/sp-create-arrow-scaled.png?fit=max&auto=format&n=GrWfTlqud5HZFYRl&q=85&s=51ef97e5649910e6adb60a3ae226e0f6" alt="Create service principal" width="1276" height="303" data-path="images/get-started/service-principals/sp-create-arrow-scaled.png" />
    </Frame>
  </Step>

  <Step>
    Assign a **Name** to your service principal. Your service principal's name can only include alphanumeric characters.
  </Step>

  <Step>
    Click **Submit**.
  </Step>
</Steps>

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](/get-started/wherobots-cloud/service-principals#rename-service-principal)
* [Assign API keys to a service principal](/get-started/wherobots-cloud/service-principals#add-an-api-key-to-a-service-principal)
* [Delete a service principal](/get-started/wherobots-cloud/service-principals#delete-a-service-principal)

#### Find your service principal

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

<Steps>
  <Step>
    Login to your Professional or Enterprise Edition [Wherobots Organization](https://cloud.wherobots.com/).
  </Step>

  <Step>
    Go to [**Organization Settings > Service Principals**](https://cloud.wherobots.com/organization#service-principals).
  </Step>

  <Step>
    Click the service principal that you want to modify. You will be taken to that service principal's detail page.

    <Frame>
      <img src="https://mintcdn.com/wherobots/GrWfTlqud5HZFYRl/images/get-started/service-principals/sp-page.png?fit=max&auto=format&n=GrWfTlqud5HZFYRl&q=85&s=1ebbdc0b72a337250de42444c21ff661" alt="Service principal detail page" width="2134" height="1440" data-path="images/get-started/service-principals/sp-page.png" />
    </Frame>
  </Step>
</Steps>

#### Rename service principal

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

<Steps>
  <Step>
    Follow the steps in [Find your service principal](/get-started/wherobots-cloud/service-principals#find-your-service-principal).
  </Step>

  <Step>
    Edit the **Name** field.
  </Step>

  <Step>
    Click **Save**.
  </Step>
</Steps>

#### Add an API key to a service principal

<Steps>
  <Step>
    Follow the steps in [Find your service principal](/get-started/wherobots-cloud/service-principals#find-your-service-principal).
  </Step>

  <Step>
    Scroll to **API keys**.
  </Step>

  <Step>
    Click **Create New Key**. [    <img src="https://mintcdn.com/wherobots/GrWfTlqud5HZFYRl/images/get-started/service-principals/api-keys-arrow.png?fit=max&auto=format&n=GrWfTlqud5HZFYRl&q=85&s=e89747b6f59cba52669e16c4f18550cf" alt="Create new API key" width="2114" height="609" data-path="images/get-started/service-principals/api-keys-arrow.png" />](/images/get-started/service-principals/api-keys-arrow.png)
  </Step>

  <Step>
    Enter a value in the **Name** field.
  </Step>

  <Step>
    Choose an Expiration Date for your API key. This value defaults to 1 year from when the API key is created.
  </Step>

  <Step>
    Click **Submit**.
  </Step>
</Steps>

After clicking **Submit**, Wherobots generates an API key.

<Note>
  ### Note

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

#### 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:

<Steps>
  <Step>
    Follow the steps in [Find your service principal](/get-started/wherobots-cloud/service-principals#find-your-service-principal).
  </Step>

  <Step>
    Review the service principal's associated API keys. Deleting the service principal will also revoke its API keys.
  </Step>

  <Step>
    Click **Delete service principal**.

    <Frame>
      <img src="https://mintcdn.com/wherobots/GrWfTlqud5HZFYRl/images/get-started/service-principals/sp-delete-arrow.png?fit=max&auto=format&n=GrWfTlqud5HZFYRl&q=85&s=ba5b7755d91518438749679d14a2334a" alt="Delete service principal" width="2124" height="279" data-path="images/get-started/service-principals/sp-delete-arrow.png" />
    </Frame>
  </Step>

  <Step>
    When asked to confirm if you want to delete the service principal, click **Delete**.
  </Step>
</Steps>

## 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:

<Steps>
  <Step>
    Go to [**Organization Settings > Users**](https://cloud.wherobots.com/organization#users).
  </Step>

  <Step>
    Find the email address associated with the **Admin** in your Organization.

    <Frame>
      <img src="https://mintcdn.com/wherobots/GrWfTlqud5HZFYRl/images/get-started/service-principals/user-page.png?fit=max&auto=format&n=GrWfTlqud5HZFYRl&q=85&s=21f2f1b24f865b3af74c5b4c9a950c15" alt="Delete service principal" width="1196" height="273" data-path="images/get-started/service-principals/user-page.png" />
    </Frame>
  </Step>
</Steps>

## 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:

<Steps>
  <Step>
    Manually revoke those initial API keys from your Organization.

    <Steps>
      <Step>
        Log in to your [Wherobots Organization](https://cloud.wherobots.com/).
      </Step>

      <Step>
        Go to [**Organization Settings > Security**](https://cloud.wherobots.com/organization#security).
      </Step>

      <Step>
        Find **API Keys** section.
      </Step>

      <Step>
        Locate the **Owned by** column.
      </Step>

      <Step>
        Identify API keys owned by individuals rather than a service principal.
      </Step>

      <Step>
        Scroll to the right and click **... > Revoke**.

        <Frame>
          <img src="https://mintcdn.com/wherobots/GrWfTlqud5HZFYRl/images/get-started/service-principals/api-keys-revoke.png?fit=max&auto=format&n=GrWfTlqud5HZFYRl&q=85&s=afefbbf2ffb54bf580a3d56514504699" alt="Revoke API key" width="3004" height="1190" data-path="images/get-started/service-principals/api-keys-revoke.png" />
        </Frame>
      </Step>

      <Step>
        Click **Revoke** to confirm that you want to remove this API key from your Organization.
      </Step>
    </Steps>
  </Step>

  <Step>
    [Create a new service principal](/get-started/wherobots-cloud/service-principals#create-a-service-principal).
  </Step>

  <Step>
    [Add an API key to that service principal](/get-started/wherobots-cloud/service-principals#add-an-api-key-to-a-service-principal).
  </Step>
</Steps>