# Setup & Authentication

## Setup

Before being able to utilize the CIPP API, you need to first configure an API client via [cipp-api](https://docs.cipp.app/user-documentation/cipp/integrations/cipp-api "mention"). Once that is completed, come back to this page. You'll need the integration page still open to reference the necessary fields below for authentication.

{% hint style="warning" %}

#### Self-Hosted Clients

If you originally deployed CIPP prior to v7.1 you will need to follow the instructions on [self-hosted-api-setup](https://docs.cipp.app/setup/self-hosting-guide/self-hosted-api-setup "mention")
{% endhint %}

## Authentication

CIPP uses OAuth authentication to be able to connect to the API using your Application ID and Secret. You can use the PowerShell example below to connect to the API:

```powershell
$CIPPAPIUrl = "https://yourcippurl.com"
$ApplicationId = "your application ID"
$ApplicationSecret = "your application secret"
$TenantId = "your tenant id"

$AuthBody = @{
    client_id     = $ApplicationId
    client_secret = $ApplicationSecret
    scope         = "api://$($ApplicationId)/.default"
    grant_type    = 'client_credentials'
}
$token = Invoke-RestMethod -Uri "https://login.microsoftonline.com/$TenantId/oauth2/v2.0/token" -Method POST -Body $AuthBody

$AuthHeader = @{ Authorization = "Bearer $($token.access_token)" }
Invoke-RestMethod -Uri "$CIPPAPIUrl/api/ListLogs" -Method GET -Headers $AuthHeader -ContentType "application/json"

```

{% hint style="info" %}
If you are making an OAuth connection with any 3rd party service, make use of the copyable fields on the [cipp-api](https://docs.cipp.app/user-documentation/cipp/integrations/cipp-api "mention") integration page indicated by a blue outline. You will also need the API Scope, get this from the CIPP-API Clients table by clicking the Actions three dots for the row you are configuring and selecting `Copy API Scope`.
{% endhint %}

### Time and Rate Limits

The API actions have a maximum timeout of 10 minutes. There are no active rate limits, but heavy usage of the API can cause frontend operations to slow down.

## Endpoint documentation

{% content-ref url="endpoints" %}
[endpoints](https://docs.cipp.app/api-documentation/endpoints)
{% endcontent-ref %}

## CIPP API Powershell Module

You can install the CIPP API Powershell module using PowerShell 7.x. The module takes care of all the authentication for you.

```powershell
Install-Module -Name CIPPAPIModule
```

You will first need to set your CIPP API Details using the following command:

```powershell
Set-CIPPAPIDetails -CIPPClientID "YourClientIDGoesHere" -CIPPClientSecret "YourClientSecretGoesHere" -CIPPAPIUrl "https://your.cipp.apiurl" -TenantID "YourTenantID"
```

You can then test its working

```powershell
Get-CIPPLogs
```

Further documentation for the module and each of its available functions can be found [here](https://github.com/BNWEIN/CIPPAPIModule/).

{% hint style="info" %}
This module is created and maintained by a community member. With CIPP's rapid development cycle, the module can be expected to lag behind in adding new endpoints. For those, it is recommended to use the command `Invoke-CIPPRestMethod`.
{% endhint %}

## Caveats

1. If you are using an automation like N8N, you may need to add /api to the end of your URL
2. If you get any API 400 Errors like "Invoke-CIPPRestMethod: Response status code does not indicate success: 400 (Bad Request)" when first authing/testing, your cipp api client app reg may be missing an "APP ID URI". Fix this by going to your tenant, finding the app registration for the client you just made and in the "expose an api" section, you should be able to click the add button at the top of the page, which will automatilly fill in the client id and a suggested URI, once added and saved, you should try authing again.

### Feature Requests / Ideas

We value your feedback and ideas. Please raise any [feature requests](https://github.com/KelvinTegelaar/CIPP/issues/new?assignees=\&labels=enhancement%2Cno-priority\&projects=\&template=feature.yml\&title=%5BFeature+Request%5D%3A+) on GitHub.