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

# Developer Portal

> Manage API keys and webhooks from the JobTicket+ Developer Portal

## Overview

The JobTicket+ Developer Portal gives you a self-service interface to manage everything you need to integrate with the JobTicket B2B API — API keys, permissions, webhooks, and delivery logs.

<CardGroup cols={2}>
  <Card title="Production Portal" icon="arrow-up-right-from-square" href="https://jobticket-developer.ticket-plus.app" color="#16a34a">
    Access the live production developer dashboard
  </Card>

  <Card title="Staging Portal" icon="arrow-up-right-from-square" href="https://jobticket-developer-staging.ticket-plus.app" color="#2563eb">
    Access the staging developer dashboard for testing
  </Card>
</CardGroup>

The dashboard summarises your account at a glance:

| Card                  | What it shows                                                  |
| --------------------- | -------------------------------------------------------------- |
| **API Status**        | Whether API access is **ENABLED** or disabled for your account |
| **Active API Keys**   | Number of currently enabled keys                               |
| **Disabled API Keys** | Number of keys that exist but are disabled                     |
| **Total Webhooks**    | Number of webhook endpoints registered                         |

***

## Granting Developers Access

Before a developer can log in to the Developer Portal, a company admin must complete the following four steps in the **AllRide B2B Admin Panel**.

<Steps>
  <Step title="Create a Developer Admin Group">
    1. In the left navigation go to **Company management → Admin groups**.
    2. Click **+ Add new admin group** in the top-right corner.
    3. Enter a group name (e.g. `Developers`) and click **Add group**.

    The new group appears in the list with **0 Permissions**.
  </Step>

  <Step title="Grant the Group Developer Portal Permissions">
    1. Click the **⋯** menu on the `Developers` group row and select **Update group permissions**.
    2. Enable the following permissions:

    | Permission                  | Description                                           |
    | --------------------------- | ----------------------------------------------------- |
    | **Access Developer Portal** | Access and use the developer portal and its resources |
    | **View API Keys**           | View API keys and access credentials                  |
    | **View API Key Secrets**    | View API key secrets and sensitive credentials        |
    | **Create API Keys**         | Create new API keys and access credentials            |
    | **Update API Keys**         | Update existing API keys and access credentials       |
    | **View Webhooks**           | View webhook configurations and settings              |
    | **View Webhook Secrets**    | View webhook secrets and signing credentials          |
    | **Create Webhooks**         | Create new webhook configurations and endpoints       |
    | **Update Webhooks**         | Update existing webhook configurations and endpoints  |
    | **Remove Webhooks**         | Remove webhook configurations and endpoints           |
    | **View Webhook Logs**       | View webhook delivery logs and event history          |

    3. Click **Update permissions** to save.
  </Step>

  <Step title="Add the Developer as an Employee">
    1. In the left navigation go to **Jobticket+ management → Manage employees**.
    2. Click **+ Add employee** and fill in the developer's details:
       * First name, Last name, Email address
       * Date of birth
       * Set **Subscription start date** to **Don't Start Subscription** (developers do not need a Jobticket+ plan)
    3. Click **Add employee**.
  </Step>

  <Step title="Assign the Employee as an Admin in the Developer Group">
    1. In the left navigation go to **Company management → Manage admins**.
    2. Click **+ Add new admin**.
    3. In the **Select employees** step, search for and check the developer's name, then click **Next**.
    4. In the **Select groups** step, check the `Developers` group, then click **Add users**.

    The developer can now log in to the Developer Portal using their employee email address and will have access to all the permissions assigned to the `Developers` group.
  </Step>
</Steps>

<Note>
  Assign only the permissions your developers actually need. Avoid enabling **View API Key Secrets** or **View Webhook Secrets** for developers who only need read access to configurations.
</Note>

***

## Authentication

Every API request uses **HTTP Basic Auth**. The credentials come from an API key you create in the portal:

| Basic Auth field | Value                                                               |
| ---------------- | ------------------------------------------------------------------- |
| **Username**     | API Key ID (e.g. `f1b24afa-39c6-4cc2-b545-cfab6b687f6e`)            |
| **Password**     | API Key Secret (revealed via **View API Key Secret** in the ⋯ menu) |

```http theme={null}
Authorization: Basic <base64(apiKeyId:apiKeySecret)>
```

<Note>
  Most HTTP clients (e.g. `curl -u`, Axios `auth`, Python `requests` `auth=`)
  handle the Base64 encoding automatically when you supply a username and
  password separately.
</Note>

***

## API Keys

### Permissions

Each API key carries a set of **permissions** that control which endpoints it can call. The portal shows the count (e.g. *5 Permissions*) on the key list. Click the count to see the full list assigned to that key.

Available permissions and what they unlock:

| Permission                                                      | Description                                                                                                | Endpoints covered                                                                  |
| --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| **View Employees** (`view-employees`)                           | Allows the API key to view the list of employees, their details, and their documents within the company.   | List Employees, Get Employee, List Documents, Get Document, Get Employee Documents |
| **Add New Employees** (`add-employees`)                         | Enables the API key to add new employees to the company, including setting up their roles and permissions. | Used internally during HR sync                                                     |
| **Update Existing Employee Details** (`update-employees`)       | Allows modification of existing employee details such as role, department, and contact information.        | Used internally during HR sync                                                     |
| **Remove Existing Employees From Company** (`remove-employees`) | Grants permission to remove employees from the company and deactivate their accounts.                      | Used internally during HR sync                                                     |
| **View HR Integrations** (`view-hr-integrations`)               | View HR integration connections and settings.                                                              | List HR Integrations, Get HR Integration                                           |

A key only succeeds on endpoints that match its permissions — all others return `403 Forbidden`.

***

### Creating an API Key

<Steps>
  <Step title="Open API Keys">
    In the left navigation click **API Keys**, then click **+ Add New Api Key** in the top-right corner.
  </Step>

  <Step title="Enter a description">
    Type a descriptive label in the **API Key Description** field (e.g. `Production – Payroll System`) and click **Create API Key**.
  </Step>

  <Step title="Copy your credentials">
    After creation, click the **⋯** menu on the key row and select **View API Key Secret** to reveal the secret. Copy the **API Key ID** and **API Key Secret** and store them in a secret manager.

    <Warning>
      If you need to replace a compromised or lost secret, use **Rotate API Key Secret** to generate a new one. The old secret is immediately invalidated.
    </Warning>
  </Step>

  <Step title="Assign permissions">
    Click the **⋯** menu on the new key row and select **Update API Key permissions** to grant the scopes your integration needs.
  </Step>
</Steps>

***

### Managing API Keys

Click the **⋯** menu on any key row to access:

| Action                         | What it does                                                          |
| ------------------------------ | --------------------------------------------------------------------- |
| **View API Key Secret**        | Reveals the current secret (requires confirmation)                    |
| **Update API Key permissions** | Opens a permissions editor to add or remove scopes                    |
| **Rotate API Key Secret**      | Generates a new secret and immediately invalidates the old one        |
| **Disable API Key**            | Revokes API access without deleting the key — can be re-enabled later |

***

## Webhooks

Webhooks let JobTicket+ push real-time events to your server so you don't need to poll the API. When a subscribed event occurs, JobTicket+ makes an HTTP `POST` to your endpoint with a signed JSON payload.

See [Webhooks](/v1/webhooks) for the full payload schemas and signature verification guide.

### Creating a Webhook

<Steps>
  <Step title="Open Webhooks">
    In the left navigation click **Webhooks**, then click **+ Add New Webhook**.
  </Step>

  <Step title="Fill in the form">
    | Field                   | Description                              |
    | ----------------------- | ---------------------------------------- |
    | **Webhook Description** | A friendly label (required)              |
    | **Webhook URL**         | The HTTPS URL JobTicket+ should POST to  |
    | **Event Types**         | Check one or more events to subscribe to |

    Available event types:

    | Event                             | Fires when…                                       |
    | --------------------------------- | ------------------------------------------------- |
    | `employee-subscription-changed`   | An employee's subscription status or dates change |
    | `new-employee-document-generated` | A new document is generated for an employee       |
  </Step>

  <Step title="Submit">
    Click **Add webhook**. The webhook is active immediately.
  </Step>
</Steps>

***

### Managing Webhooks

Click the **⋯** menu on any webhook row:

| Action                                   | What it does                                                  |
| ---------------------------------------- | ------------------------------------------------------------- |
| **View Webhook Logs**                    | Navigate to filtered delivery logs for this webhook           |
| **View Webhook Signing Secrets**         | Reveal the two signing secrets used to verify payloads        |
| **Update Webhook**                       | Change the URL, description, or subscribed events             |
| **Rotate First Webhook Signing Secret**  | Generates a new first secret; old one is immediately invalid  |
| **Rotate Second Webhook Signing Secret** | Generates a new second secret; old one is immediately invalid |
| **Delete Webhook**                       | Permanently removes the webhook and stops all deliveries      |

<Note>
  Two signing secrets exist to support **zero-downtime rotation**. Both are
  valid simultaneously — rotate one while the other keeps requests flowing, then
  retire the old one. See [Verifying
  Signatures](/v1/webhooks#verifying-signatures) for details.
</Note>

***

### Webhook Logs

The **Webhook Logs** section records every delivery attempt. Each row shows:

| Column             | Description                                 |
| ------------------ | ------------------------------------------- |
| **Webhook Log ID** | Unique ID of the delivery attempt           |
| **Event ID**       | ID of the event that triggered the delivery |
| **URL**            | The endpoint JobTicket+ posted to           |
| **Event Type**     | The event type label                        |
| **Status Code**    | HTTP status returned by your server         |
| **Logged At**      | Timestamp of the delivery attempt           |

Click **View Webhook Log** on any row to inspect the full details — including the raw JSON payload, the `X-Signing-Signature` header value, and your server's response body. This is your primary debugging tool when a delivery fails or produces an unexpected response.