# API Overview

Welcome to the **SM API** — this guide helps you get started quickly using Postman, configure authentication, and make your first successful API call.

---

## Setting Up Postman

1. Download and install **[Postman](https://www.postman.com/downloads/)**.

2. Click the **Run in Postman** button below to automatically import our API collection into your workspace.

[](https://app.getpostman.com/run-collection/{{YOUR_COLLECTION_ID}})

3. Once imported, open the **"Environment"** tab in Postman and create a new environment named `CraterLabs` with the following variables:

| Variable | Example Value | Description |

|-----------|----------------|-------------|

| `baseUrl` | `https://api.craterlabs.homelab` | The root API endpoint |

| `tenantId` | `YOUR_TENANT_ID` | Azure AD tenant or Auth0 domain |

| `clientId` | `YOUR_CLIENT_ID` | Application client ID |

| `clientSecret` | `YOUR_CLIENT_SECRET` | Application secret |

| `tokenUrl` | `https://login.microsoftonline.com/{{tenantId}}/oauth2/v2.0/token` | OAuth2 token endpoint |

| `accessToken` | *(automatically set after auth step)* | Bearer token used for requests |

---

## Authentication

This API uses **OAuth 2.0 Client Credentials Flow**.

1. In Postman, open the **"Authorization"** tab.

2. Set **Type** to `OAuth 2.0`.

3. Click **Get New Access Token** and fill out the following:

| Field | Value |

|--------|--------|

| Grant Type | Client Credentials |

| Access Token URL | `{{tokenUrl}}` |

| Client ID | `{{clientId}}` |

| Client Secret | `{{clientSecret}}` |

| Scope | `api://{{clientId}}/.default` |

| Client Authentication | Send as Basic Auth header |

4. Click **Request Token**.

Once received, Postman will store it as `{{accessToken}}`.

You can now select **"Use Token"** to authorize requests automatically.

---

## Making Your First Request

Open the **"Sample Requests"** folder in the imported collection and select **"Get Users"**.

Ensure the environment is set to `CraterLabs`.

**GET** `{{baseUrl}}/api/users`

Under the **Headers** tab, Postman should automatically insert:

```bash

Authorization: Bearer {{accessToken}}

```

Click **Send** and you should receive a `200 OK` response containing a list of users.

---

## Troubleshooting

- **401 Unauthorized:** Check if your token has expired and re-authenticate.

- **404 Not Found:** Verify that the `baseUrl` is correct for your environment.

- **CORS or Gateway errors:** Confirm your client app is registered in the correct Azure AD tenant and has API permissions granted.

---

## Next Steps

- Review the [API Reference](/apis/craterlabs) for full operation details.

- Explore advanced examples for batch uploads and webhook subscriptions.

- Visit our [Authentication Guide](/auth-flow) for deeper OAuth integration details.

---

*Last updated: October 2025*