> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developer.deel.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.deel.com/_mcp/server.

# Getting started

> Prerequisites, authentication, environments, and webhook setup for Embedded partners.

This page covers the common setup required before working with any Embedded API guide. Complete these steps once before building employer or worker flows.

## Prerequisites

#### Embedded partnership enabled

Your Deel account must have the Embedded model activated before any Embedded API flows are available. Contact your Deel implementation engineer to confirm your account is configured.

#### Admin API token

All employer-side endpoints require an organization-level API token. See [Get your API credentials](/api/quickstart#get-your-api-credentials) for instructions on generating a token. Store it as an environment variable; never hardcode tokens in application code.

#### Legal entity configured (EOR only)

EOR contract creation requires at least one legal entity on your account. Retrieve your legal entities via [`GET /legal-entities`](/api/reference/endpoints/legal-entities/get-legal-entities) and store the `id` for use in contract payloads.

## Authentication

### Admin token (employer-side)

All employer-facing endpoints authenticate with an organization-level API token passed as a Bearer token in the `Authorization` header.

```
Authorization: Bearer YOUR_API_TOKEN
```

See [Authentication](/api/authentication) for token scopes and generation instructions.

### OAuth (optional)

If your platform uses OAuth to act on behalf of your clients rather than a single shared admin token, refer to the [OAuth guide](/api/oauth) for the authorization code flow.

### Worker tokens (Full Embedded)

Worker-side endpoints use a separate worker-scoped token. In the Full Embedded model, your platform generates this server-side and passes it to the worker's session:

Call [`POST /workers/session`](/api/reference/endpoints/worker-session/create-worker-access-token-v-2026-01-01) with your admin token and a `contract_id` to receive a short-lived worker token.

Use the returned `token` in the `Authorization` header for all worker-scoped requests. Worker tokens are scoped to a single contract and valid for 24 hours.

### Magic links

To use Deel's hosted worker experience, redirect workers to a magic link rather than calling worker APIs directly:

Call [`POST /magic-link`](/api/reference/endpoints/magic-link/create-magic-link) to generate a short-lived link (valid for 5 minutes) that takes the worker into the Deel onboarding UI.

> **Note**
>
> With magic links, you do not call worker-scoped endpoints directly. The worker token flow applies when you are handling worker flows within your own platform.

## Environments

| Environment    | Base URL                                |
| -------------- | --------------------------------------- |
| Production     | `https://api.letsdeel.com/rest`         |
| Demo (sandbox) | `https://api-staging.letsdeel.com/rest` |

> **Warning**
>
> All contract and amendment operations are legally binding in production. Test every flow in the sandbox environment before connecting to production data.

## Webhooks

Webhooks are the recommended way to track state changes. All Embedded guides reference specific events; subscribing to these eliminates polling and makes your integration more reliable.

To configure webhooks, see the [Webhooks guide](/api/webhooks/introduction). Key setup steps:

1. Register a webhook endpoint URL in your Deel account settings.
2. Store the signing secret and verify the `X-Deel-Signature` header on every incoming event.
3. Respond with `200 OK` within 10 seconds; Deel retries failed deliveries.

## Multi-tenant structure

In the Embedded model, each of your end customers is represented as a **group** in Deel. Create one group per customer company during their onboarding via [`POST /groups`](/api/reference/endpoints/groups/create-group). The `id` returned maps to the `client.team` field in all EOR and IC contract requests for that customer.

Use `external_metadata` to store your platform's internal identifiers on each group, so you can reconcile records across systems without a separate mapping table.

## Next steps

#### [Hiring & contracts](/api/embedded/eor-hiring)

Group setup, cost estimation, EOR contract creation, and employer signing.

#### [Hiring & contracts](/api/embedded/ic-create-onboard)

IC contract creation, document attachment, and worker invitation.

#### [Worker onboarding](/api/embedded/eor-worker-onboarding)

Worker-side contract signing, compliance documents, KYC, and bank setup.

#### [Manage contracts](/api/embedded/ic-manage)

Amendments, invoices, timesheets, and termination for active IC contracts.