> ## Documentation Index
> Fetch the complete documentation index at: https://developers.teleship.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authorize App

> Initiates OAuth 2.0 authorization for partner applications.

## Setup

Create an OAuth app in **Teleship Shipper Portal** to get your `clientId` and `clientSecret`.

## Usage

**1. Start authorization:**

```javascript
const state = crypto.randomUUID();
sessionStorage.setItem('oauth_state', state);

window.location.href = `https://api.teleship.com/oauth/authorize?${new URLSearchParams({
  clientId: 'your_client_id',
  responseType: 'code',
  redirectUri: 'https://yourapp.com/callback',
  scope: 'read_accounts write_shipments',
  state: state
})}`;
```

**2. Handle callback:**

```javascript
const params = new URLSearchParams(window.location.search);
const code = params.get('code');
const accountClientId = params.get('account_client_id');
const accountClientSecret = params.get('account_client_secret');
const state = params.get('state');

// Validate state
if (state !== sessionStorage.getItem('oauth_state')) throw new Error('Invalid state');
```

**3. Get access token:**

```javascript
const response = await fetch('https://api.teleship.com/oauth/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    clientId: accountClientId,
    clientSecret: accountClientSecret
  })
});

const { accessToken } = await response.json();
```

**4. Make API calls:**

```javascript
fetch('https://api.teleship.com/api/shipments', {
  headers: { 'Authorization': `Bearer ${accessToken}` }
});
```

## Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `clientId` | Yes | OAuth app client ID |
| `responseType` | Yes | Must be `code` |
| `redirectUri` | Yes | Callback URL |
| `scope` | Yes | Space-separated permissions |
| `state` | Recommended | CSRF token |

## Scopes

- `read_accounts` `write_accounts` `read_shipments` `write_shipments`



## OpenAPI

````yaml /api-reference/openapi.json get /oauth/authorize
openapi: 3.0.0
info:
  title: Teleship
  description: >

    Teleship is a leading cross-border logistics provider offering seamless
    global commerce solutions through our comprehensive API.


    With Teleship's API, developers can integrate our cross-border shipping
    services, trade engine, and logistics solutions directly into their
    applications.


    **Key Features:**

    - Cross-border shipping solutions for international commerce

    - Real-time shipping rates and delivery estimates

    - End-to-end shipment tracking with detailed status updates

    - Automated customs compliance and product classification

    - Real-time event notifications through webhooks


    **Why Teleship?**

    - API-first: Developer-friendly integration with comprehensive documentation

    - Enterprise-ready: Built for businesses of all sizes

    - Secure: Enterprise-grade security and compliance

    - Integrated: Seamless connection with e-commerce, ERP, and fulfillment
    systems


    Start shipping globally with Teleship's powerful cross-border logistics API.
  version: 1.0.0
  contact: {}
servers:
  - url: https://api.teleship.com
security: []
tags: []
paths:
  /oauth/authorize:
    get:
      tags:
        - Authentication
      summary: Authorize App
      description: >-
        Initiates OAuth 2.0 authorization for partner applications.


        ## Setup


        Create an OAuth app in **Teleship Shipper Portal** to get your
        `clientId` and `clientSecret`.


        ## Usage


        **1. Start authorization:**


        ```javascript

        const state = crypto.randomUUID();

        sessionStorage.setItem('oauth_state', state);


        window.location.href = `https://api.teleship.com/oauth/authorize?${new
        URLSearchParams({
          clientId: 'your_client_id',
          responseType: 'code',
          redirectUri: 'https://yourapp.com/callback',
          scope: 'read_accounts write_shipments',
          state: state
        })}`;

        ```


        **2. Handle callback:**


        ```javascript

        const params = new URLSearchParams(window.location.search);

        const code = params.get('code');

        const accountClientId = params.get('account_client_id');

        const accountClientSecret = params.get('account_client_secret');

        const state = params.get('state');


        // Validate state

        if (state !== sessionStorage.getItem('oauth_state')) throw new
        Error('Invalid state');

        ```


        **3. Get access token:**


        ```javascript

        const response = await fetch('https://api.teleship.com/oauth/token', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({
            clientId: accountClientId,
            clientSecret: accountClientSecret
          })
        });


        const { accessToken } = await response.json();

        ```


        **4. Make API calls:**


        ```javascript

        fetch('https://api.teleship.com/api/shipments', {
          headers: { 'Authorization': `Bearer ${accessToken}` }
        });

        ```


        ## Parameters


        | Parameter | Required | Description |

        |-----------|----------|-------------|

        | `clientId` | Yes | OAuth app client ID |

        | `responseType` | Yes | Must be `code` |

        | `redirectUri` | Yes | Callback URL |

        | `scope` | Yes | Space-separated permissions |

        | `state` | Recommended | CSRF token |


        ## Scopes


        - `read_accounts` `write_accounts` `read_shipments` `write_shipments`
      operationId: authorizeApp
      parameters:
        - name: clientId
          required: true
          in: query
          description: OAuth client identifier
          schema:
            example: app_xxxxxxxx
            type: string
        - name: responseType
          required: true
          in: query
          description: OAuth response type (must be "code")
          schema:
            example: code
            type: string
        - name: scope
          required: true
          in: query
          description: OAuth scopes being requested (space-separated)
          schema:
            example: write_shipments write_orders
            type: string
        - name: redirectUri
          required: true
          in: query
          description: OAuth redirect URI
          schema:
            example: https://partner.com/oauth/callback
            type: string
        - name: state
          required: false
          in: query
          description: OAuth state parameter for CSRF protection
          schema:
            example: random-state-string
            type: string
      responses:
        '302':
          description: Redirect to UI for OAuth flow
          headers:
            Location:
              description: Redirect URL to UI
              schema:
                type: string
                example: >-
                  http://api.teleship.com/oauth/signin?clientId=abc&redirectUri=xyz
        '400':
          description: Bad request - invalid OAuth parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseMessagesDto'
        '401':
          description: Unauthorized - invalid client
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthErrorResponseDto'
components:
  schemas:
    ResponseMessagesDto:
      type: object
      properties:
        messages:
          type: array
          items:
            $ref: '#/components/schemas/ErrorResponseDto'
      required:
        - messages
    OAuthErrorResponseDto:
      type: object
      properties:
        success:
          type: boolean
          description: Success status
          example: false
        error:
          type: object
          description: Error details
          example:
            code: 401
            message: Invalid clientId or redirectUri
      required:
        - success
        - error
    ErrorResponseDto:
      type: object
      properties:
        code:
          type: number
        level:
          type: string
          enum:
            - error
            - warning
            - info
          example: error
          description: Error level
          default: error
        timestamp:
          format: date-time
          type: string
          example: '2024-01-01T00:00:00.00Z'
        message:
          type: string
          example: An error occurred
        details:
          example:
            - Missing required field
          type: array
          items:
            type: string
      required:
        - code
        - level
        - timestamp
        - message
        - details

````