For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
SupportDeel Home
OverviewPlatformEmployer of RecordContractorsGlobal PayrollHREmbeddedDeel ITAPI ReferenceChangelog
OverviewPlatformEmployer of RecordContractorsGlobal PayrollHREmbeddedDeel ITAPI ReferenceChangelog
  • Resources
    • Blog
    • Community
    • API spec
  • Get Started
    • Quickstart
    • Sandbox
  • Essentials
    • Authentication
    • API versioning
    • OAuth 2.0
    • Rate Limits
    • Idempotency
    • Best Practices
  • Webhooks
    • Introduction
    • Quickstart
    • No Code
    • Events
    • Simulations
  • Partners
    • Introduction
    • Getting Started
    • Publishing to App Store
LogoLogo
SupportDeel Home
On this page
  • Overview
  • Prerequisites
  • Step 1: Create Your OAuth2 App
  • Step 2: Implement OAuth2 Flow
  • Step 3: Make API Calls
  • Step 4: Test in Sandbox
  • Best Practices
  • Common Pitfalls
  • Next Steps
Partners

Getting Started

Was this page helpful?
Previous

Publishing to App Store

Next
Built with

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
  • 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

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:

1

Navigate to Developer Center

Go to app.deel.com → Settings → Developer Center

2

Create New App

Click Create App and provide:

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

Save Credentials

You’ll receive:

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

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.

Detailed OAuth2 guide: For a complete explanation of OAuth2 implementation including authorization requests, token exchange, and token refresh, see our OAuth2 documentation.

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:

1async function getContracts(accessToken) {
2  try {
3    const response = await axios.get(
4      'https://api.letsdeel.com/rest/v2/contracts',
5      {
6        headers: {
7          'Authorization': `Bearer ${accessToken}`
8        }
9      }
10    );
11
12    return response.data;
13  } catch (error) {
14    if (error.response?.status === 401) {
15      // Token expired, refresh it
16      const newTokens = await refreshAccessToken(refreshToken);
17      // Retry request with new token
18      return getContracts(newTokens.accessToken);
19    }
20    throw error;
21  }
22}

Step 4: Test in Sandbox

Test your integration using Deel’s sandbox environment:

1

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-sandbox.letsdeel.com/rest/v2/
2

Create Test Data

Create test contracts and workers in sandbox to verify your integration

3

Test OAuth Flow

Complete the full OAuth flow with sandbox credentials

4

Test API Operations

Verify all API operations work correctly:

  • Read operations (GET)
  • Create operations (POST)
  • Update operations (PATCH)
  • Error handling
5

Test Token Refresh

Ensure token refresh works properly before tokens expire

Ready to publish? Once you’ve built and tested your app, check out the 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

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

Deep dive into OAuth2 implementation

Publish to App Store

Submit your app for marketplace listing