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

# Service Accounts

> Configure service accounts by leveraging Oauth2 Client Credentials Grant Type

## Pre-requisites

* Hoop Gateway Self Hosted instance
* Identity Provider that support **[OAuth 2.0 Client Credentials Grant flow](https://www.oauth.com/oauth2-servers/access-tokens/client-credentials/).**

<Note>
  Not all identity providers support the OAuth 2.0 Client Credentials Grant flow.
  Before implementing this guide, consult your identity provider's documentation to verify compatibility.
</Note>

## Setup

<Steps>
  <Step title="Obtain an Access Token">
    Usually to obtain an access token you must know the Oauth2 Authorization Server URL.
    This configuration may differ depending on your identity provider.

    The example below shows how to obtain an access token from the [Azure Microsoft Entra ID Identity Provider](/setup/configuration/idp/azure)

    ```sh theme={"dark"}
    curl -XPOST -H "Content-Type: application/x-www-form-urlencoded" \
        -d client_id=<oauth2-client-id> \
        -d scope=<oauth2-client-id>/.default \
        -d client_secret=<oauth2-client-secret> \
        -d grant_type=client_credentials \
        https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token
    ```

    A success response generates the following payload:

    ```json theme={"dark"}
    {
        "token_type": "Bearer",
        "expires_in": 3599,
        "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni..."
    }
    ```

    The `access_token` attribute value is used to communicate with the Hoop Gateway API.

    <Note>
      In order to obtain always a valid access token programatically you must automate the issuing
      of this process in your automation workflow.
    </Note>
  </Step>

  <Step title="Create the Service Account">
    This step creates the service account resource by establishing an association with the `sub` claim that is returned when the access token is issued.

    <Info>
      This information typically corresponds to the `client_id` attribute in your OAuth 2.0 credentials.
      For detailed instructions specific to your identity provider, refer to [our getting started section documentation](/setup/configuration/idp/get-started).

      If you're having trouble locating this information, consult your identity provider's configuration guide.
    </Info>

    <Tabs>
      <Tab title="Admin Privileged Access">
        It creates an **administrator user** with access to all resources in the API.

        ```sh theme={"dark"}
        hoop admin create serviceaccount <access-token-identifier> \
            --groups admin \
            --name 'Admin Api User Programmatic Access'
        ```
      </Tab>

      <Tab title="Non Admin Privileged Access">
        It creates a regular access user with **non privileged access** that belong to groups `devops` and `ops`

        ```sh theme={"dark"}
        hoop admin create serviceaccount <access-token-identifier> \
            --groups devops,ops \
            --name 'Api User Programmatic Access'
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Use the Access Token">
    Configure your client application to use this token to access the Hoop API.
    An example using `curl` (http client) would be:

    ```sh theme={"dark"}
    curl --verbose -H "Authorization: Bearer $HOOP_TOKEN" \
        https://hoop-gateway-url/api/userinfo
    ```

    It should respond with HTTP status code 200 and return a JSON payload with the user information.
  </Step>
</Steps>

## Revoking Access

The command below disable the service account by invalidating any request being sent to the gateway.

```sh theme={"dark"}
hoop admin create serviceaccount api-user \
    --groups admin \
    --name 'Admin Api User Programmatic Access' \
    --disable
```

<Note>
  It's important to note that the access token has an expiration time as well.
  The Hoop Gateway API provides additional mechanisms to deny access for this service account through its association with the `subject` identifier in the token.
</Note>