> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.deel.wtf/api/stable/partners/getting-started/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.deel.wtf/_mcp/server.

# Getting Started

> Build your first OAuth2 app with Deel

## Overview

This guide walks you through building your first OAuth2 app with Deel, from initial setup to submitting for App Store review. You'll learn how to implement OAuth2 authentication, make API calls, and prepare your app for production.

## Prerequisites

Before you begin, you'll need:

#### Deel Account

* Go to [app.deel.com](https://app.deel.com)
* Click **Sign Up** and complete the registration process

#### Technical Knowledge

Basic understanding of:

* OAuth2 authorization flow
* RESTful API concepts
* HTTPS and web security
* Backend development (Node.js, Python, etc.)

#### Development Environment

Set up your development environment:

* Code editor or IDE
* Backend framework of your choice
* Testing tools (Postman, curl, etc.)
* ngrok or similar for local testing

> **Tip**
>
> **Get in touch:** We recommend reaching out to our partnership team before you start building. We can provide guidance, answer questions, and help you succeed.

## Step 1: Create Your OAuth2 App

Register your application in the Developer Center:

#### Navigate to Developer Center

Go to [app.deel.com](https://app.deel.com) → **Settings** → **Developer Center**

#### Create New App

Click **Create App** and provide:

* App name
* Description
* Redirect URIs (e.g., `https://yourapp.com/callback`)
* Webhook URL (optional)

#### Save Credentials

You'll receive:

* **Client ID**: Public identifier for your app
* **Client Secret**: Keep this secure, never expose it

> **Warning**
>
> Store your Client Secret securely. You won't be able to view it again after this screen.

## Step 2: Implement OAuth2 Flow

Implement Deel's OAuth2 authorization code flow to authenticate users and obtain access tokens.

> **Info**
>
> **Detailed OAuth2 guide:** For a complete explanation of OAuth2 implementation including authorization requests, token exchange, and token refresh, see our [OAuth2 documentation](/api/oauth).

**Quick overview:**

1. Redirect users to Deel's authorization endpoint
2. User authorizes your app
3. Exchange authorization code for access and refresh tokens
4. Store tokens securely
5. Use access token for API requests
6. Refresh tokens automatically when they expire

## Step 3: Make API Calls

Use the access token to call Deel APIs:

**`Node.js`**

```javascript Node.js
async function getContracts(accessToken) {
  try {
    const response = await axios.get(
      'https://api.letsdeel.com/rest/contracts',
      {
        headers: {
          'Authorization': `Bearer ${accessToken}`
        }
      }
    );

    return response.data;
  } catch (error) {
    if (error.response?.status === 401) {
      // Token expired, refresh it
      const newTokens = await refreshAccessToken(refreshToken);
      // Retry request with new token
      return getContracts(newTokens.accessToken);
    }
    throw error;
  }
}
```

**`Python`**

```python Python
def get_contracts(access_token):
    try:
        response = requests.get(
            'https://api.letsdeel.com/rest/contracts',
            headers={
                'Authorization': f'Bearer {access_token}'
            }
        )

        if response.status_code == 401:
            # Token expired, refresh it
            new_tokens = refresh_access_token(refresh_token)
            # Retry request with new token
            return get_contracts(new_tokens['access_token'])

        return response.json()
    except Exception as e:
        print(f'API call failed: {e}')
        raise
```

## Step 4: Test in Sandbox

Test your integration using Deel's sandbox environment:

#### Switch to Sandbox

Use sandbox endpoints for testing:

* Auth: `https://app-sandbox.letsdeel.com/oauth/authorize`
* Token: `https://app-sandbox.letsdeel.com/oauth/token`
* API: `https://api-staging.letsdeel.com/rest/`

#### Create Test Data

Create test contracts and workers in sandbox to verify your integration

#### Test OAuth Flow

Complete the full OAuth flow with sandbox credentials

#### Test API Operations

Verify all API operations work correctly:

* Read operations (GET)
* Create operations (POST)
* Update operations (PATCH)
* Error handling

#### Test Token Refresh

Ensure token refresh works properly before tokens expire

> **Info**
>
> **Ready to publish?** Once you've built and tested your app, check out the [Publishing to App Store](/api/partners/publishing-to-app-store) guide to learn how to submit your app for review.

## Best Practices

#### Security

* Store tokens encrypted at rest
* Use HTTPS for all communications
* Never expose client secrets
* Implement proper token refresh logic
* Validate redirect URIs

#### Error Handling

* Handle 401 errors with token refresh
* Implement exponential backoff for retries
* Provide helpful error messages to users
* Log errors for debugging
* Test all error scenarios

#### Performance

* Cache API responses when appropriate
* Respect rate limits
* Use pagination for large datasets
* Monitor API response times
* Optimize database queries

#### User Experience

* Clear OAuth authorization screen
* Loading states for API calls
* Graceful degradation on errors
* Easy disconnection/reconnection flow
* Comprehensive documentation

## Common Pitfalls

> **Warning**
>
> **Avoid these common mistakes:**
>
> * Not implementing token refresh (tokens expire!)
> * Hardcoding credentials in code
> * Ignoring rate limits
> * Not handling OAuth errors properly
> * Storing tokens in plain text
> * Using synchronous API calls that block

## Next Steps

#### [OAuth2 Guide](/api/oauth)

Deep dive into OAuth2 implementation

#### [Publish to App Store](/api/partners/publishing-to-app-store)

Submit your app for marketplace listing

#### [Knowledge Hub API](/api/partners/knowledge-hub-api)

Retrieve country guide content for your integration

> Build apps and integrations that extend and enhance the Deel services.