# Developer Portal

The {{ app_name }} **Public API** is a machine-to-machine REST API. A program authenticates as a company — not as a person — so a nightly payroll sync runs without anyone staying logged in.

```{button-link} ../../api/index.html
:color: primary
:expand:

Open the API Reference →
```

```{tip}
Every resource, field, method, scope and error is generated from the API itself. The reference is backed by an OpenAPI 3.0 document at `https://docs.shiftavo.com/api/openapi.json`, which you can feed to any client generator. Each shard also serves the schema for the version it is running, at `{api_base}/api/public/schema/`.
```

## What you can build

- **Read** schedules, employees, timesheets, leave requests and balances, availability, work rules, and labor cost.
- **Write** shifts and assignments, availability, timesheet corrections, leave decisions, and company configuration such as locations, positions, and employment types.
- **Subscribe to webhooks** so changes reach you as they happen instead of by polling.

Full CRUD, not a read-only export: `POST` to create, `PATCH` to update, `DELETE` to remove, and `POST` to an action sub-path for lifecycle transitions.

## What it deliberately can't do

- **Sign in as a person.** Only integration credentials are accepted; an employee's own login will not work.
- **Reach another company.** One set of credentials is bound to exactly one company, server-side.
- **Read unpublished schedules.** Draft shifts stay invisible until the team can see them too.
- **Claim or award marketplace offers.** Open shifts and swaps are read-only here — those decisions stay with people.

## Getting started

```{toctree}
:maxdepth: 1

quickstart
authentication
scopes
conventions
authorizing-manager
webhooks
```

## The shape of an integration

1. Ask us for credentials (see {doc}`quickstart`). You get a **client ID**, a **client secret**, and a set of **scopes**.
2. Exchange those at the identity provider for a short-lived **access token**.
3. Read the `api_base` claim from that token — it names the host to call. Never hardcode a data host.
4. Call `{api_base}/api/public/v1/…` with `Authorization: Bearer <token>`.

## Support

Something unclear, or an endpoint you need that isn't there? Write to {{ support_email }} and include the `X-Request-Id` from the response you're asking about — every response carries one.