Industry-Standard Security

OAuth 2.0 Integration Guide

Build secure integrations that access PortTask on behalf of users. Our OAuth 2.0 implementation supports Authorization Code with PKCE, Client Credentials, and Refresh Token flows.

Authorization Code + PKCE

For web and mobile apps that act on behalf of a user. Users authorize your app through the browser with consent screen.

Client Credentials

For server-to-server integrations without user interaction. Ideal for backend services, cron jobs, and automated systems.

Refresh Tokens

Maintain long-lived sessions without re-authorization. Exchange expired access tokens for fresh ones silently.

OAuth 2.0 Flows

Choose the flow that matches your application type.

Authorization Code Flow with PKCE

User / Browser

Your Application

PortTask Auth

1User clicks "Connect PortTask" in your app. Your app generates a PKCE code_verifier and code_challenge.

2Redirect user to PortTask authorization endpoint with client_id, redirect_uri, scope, state, and code_challenge.

3PortTask shows consent screen. User reviews requested permissions and approves or denies.

4PortTask redirects back to your redirect_uri with an authorization code and the state parameter.

5Your server exchanges the code for tokens by sending the code, client_secret, and code_verifier to the token endpoint.

6PortTask returns access_token and refresh_token. Store tokens securely and use the access_token for API requests.

Step 1: Redirect to Authorization

Authorization Request

GET https://app.porttask.com/oauth/authorize?
  client_id=pt_client_aBcDeFgHiJkLmNoPqRsTu
  &redirect_uri=https://yourapp.com/callback
  &response_type=code
  &scope=port-calls:read vessels:read
  &state=random_csrf_token
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256

Step 2: Exchange Code for Tokens

Token Exchange Request

POST https://app.porttask.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&client_id=pt_client_aBcDeFgHiJkLmNoPqRsTu
&client_secret=pt_secret_YourClientSecret
&code=pt_code_receivedFromCallback
&redirect_uri=https://yourapp.com/callback
&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

Step 3: Receive Token Response

Token Response

{
  "access_token": "pt_access_eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "pt_refresh_dGhpcyBpcyBhIHJl...",
  "scope": "port-calls:read vessels:read"
}

Refreshing Access Tokens

Access tokens expire after 1 hour. Use the refresh token to obtain a new access token without requiring user re-authorization. Refresh tokens are valid for 30 days.

Refresh Token Request

POST https://app.porttask.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&client_id=pt_client_aBcDeFgHiJkLmNoPqRsTu
&client_secret=pt_secret_YourClientSecret
&refresh_token=pt_refresh_dGhpcyBpcyBhIHJl...

Access Token Lifetime

1 hour

Refresh Token Lifetime

30 days

Auth Code Lifetime

10 minutes

SDK Integration Examples

Our SDKs handle the OAuth flow for you, including PKCE, token storage, and automatic refresh.

TypeScript / Node.js

import { PortTaskOAuth } from '@porttask/sdk';

const oauth = new PortTaskOAuth({
  clientId: process.env.PORTTASK_CLIENT_ID,
  clientSecret: process.env.PORTTASK_CLIENT_SECRET,
  redirectUri: 'https://yourapp.com/callback',
});

// Step 1: Generate authorization URL
const authUrl = oauth.getAuthorizationUrl({
  scope: ['port-calls:read', 'vessels:read'],
  state: generateCSRFToken(),
});

// Step 2: Handle callback and exchange code for token
app.get('/callback', async (req, res) => {
  const { code, state } = req.query;
  verifyCSRFToken(state);

  const tokens = await oauth.exchangeCode(code);
  // tokens.accessToken, tokens.refreshToken

  // Step 3: Use the access token
  const client = oauth.getClient(tokens.accessToken);
  const portCalls = await client.portCalls.list();
});

Python

from porttask import PortTaskOAuth

oauth = PortTaskOAuth(
    client_id=os.environ["PORTTASK_CLIENT_ID"],
    client_secret=os.environ["PORTTASK_CLIENT_SECRET"],
    redirect_uri="https://yourapp.com/callback",
)

# Step 1: Generate authorization URL
auth_url = oauth.get_authorization_url(
    scope=["port-calls:read", "vessels:read"],
    state=generate_csrf_token(),
)

# Step 2: Exchange code for tokens (in your callback handler)
tokens = oauth.exchange_code(code=request.args["code"])

# Step 3: Make authenticated requests
client = oauth.get_client(tokens.access_token)
port_calls = client.port_calls.list()

View all SDK documentation

Scope Reference

Scopes define what your OAuth application can access. Request only the scopes your application needs -- users will see these permissions on the consent screen.

Scope	Description	Access Level
`read:port_calls`	Read port calls and related data	port_calls
`write:port_calls`	Create and update port calls	port_calls
`delete:port_calls`	Delete port calls	port_calls
`read:service_orders`	Read service orders	service_orders
`write:service_orders`	Create and update service orders	service_orders
`read:vendors`	Read vendor information	vendors
`write:vendors`	Manage vendor relationships	vendors
`read:vessels`	Read vessel information	vessels
`read:documents`	Read documents	documents
`write:documents`	Upload and manage documents	documents
`read:invoices`	Read invoices and billing	invoices
`write:invoices`	Create and manage invoices	invoices
`read:analytics`	Access analytics and reports	analytics
`ai:predictions`	Use AI prediction endpoints	predictions
`webhooks:manage`	Manage webhook subscriptions	manage
`admin`	Full administrative access	read

Grant Types Reference

Select the appropriate grant type based on your application architecture.

Authorization Code

PKCE Requiredauthorization_code

Standard OAuth 2.0 flow for web applications. Users authorize your app via the browser.

Best for: Web apps, mobile apps with backend

Client Credentials

client_credentials

Machine-to-machine authentication without user interaction. For server-side integrations.

Best for: Backend services, automated systems

Refresh Token

refresh_token

Exchange a refresh token for a new access token. Enables long-lived sessions.

Best for: Maintaining user sessions

Configuration Guide

Follow these steps to set up OAuth for your application.

Navigate to the PortTask Control Panel and create a new OAuth application. You will need to provide:

Application name -- displayed to users on the consent screen
Redirect URIs -- where users are sent after authorization (must be HTTPS in production)
Grant types -- authorization_code for user-facing apps, client_credentials for M2M
Scopes -- permissions your app will request from users

After registration, you will receive a Client ID and Client Secret. Store the client secret securely -- it is only shown once.

OAuth Endpoints

Endpoint	Method	Description
`/oauth/authorize`	GET	Starts the authorization flow. Redirect users here.
`/oauth/token`	POST	Exchange authorization code for tokens, or refresh an access token.
`/oauth/revoke`	POST	Revoke an access token or refresh token.
`/oauth/userinfo`	GET	Get information about the authenticated user.
`/.well-known/openid-configuration`	GET	OpenID Connect discovery document.

Security Best Practices

Always use PKCE with the Authorization Code flow, even for confidential clients. This prevents authorization code interception attacks.
Validate the state parameter on every callback to prevent CSRF attacks. Use a cryptographically random value.
Store tokens server-side. Never expose access tokens or refresh tokens in client-side JavaScript, URLs, or logs.
Use HTTPS for all redirect URIs in production. We reject non-HTTPS redirect URIs except for localhost during development.
Request minimal scopes. Only request permissions your application actually needs. Users are more likely to approve fewer permissions.
Rotate client secrets periodically. If a secret is compromised, rotate it immediately in the Control Panel.

Error Handling

OAuth errors follow the standard error response format defined in RFC 6749.

Error Code	Description	Resolution
`invalid_request`	Missing or malformed parameter	Check required parameters are present and correctly formatted
`unauthorized_client`	Client not authorized for this grant type	Verify grant type is enabled for your OAuth app
`access_denied`	User denied the authorization request	Show a message explaining why access is needed
`invalid_scope`	Requested scope exceeds allowed scopes	Only request scopes that are configured for your app
`invalid_grant`	Authorization code expired or already used	Codes expire after 10 minutes; restart the authorization flow
`invalid_client`	Client authentication failed	Verify client_id and client_secret are correct

Example Error Response

{
  "error": "invalid_grant",
  "error_description": "The authorization code has expired. Please restart the authorization flow."
}

Ready to Build Your Integration?

DevelopersOAuth 2.0

Industry-Standard Security

OAuth 2.0 Integration Guide

Build secure integrations that access PortTask on behalf of users. Our OAuth 2.0 implementation supports Authorization Code with PKCE, Client Credentials, and Refresh Token flows.

Authorization Code + PKCE

For web and mobile apps that act on behalf of a user. Users authorize your app through the browser with consent screen.

Client Credentials

For server-to-server integrations without user interaction. Ideal for backend services, cron jobs, and automated systems.

Refresh Tokens

Maintain long-lived sessions without re-authorization. Exchange expired access tokens for fresh ones silently.

OAuth 2.0 Flows

Choose the flow that matches your application type.

Authorization Code Flow with PKCE

User / Browser

Your Application

PortTask Auth

1User clicks "Connect PortTask" in your app. Your app generates a PKCE code_verifier and code_challenge.

2Redirect user to PortTask authorization endpoint with client_id, redirect_uri, scope, state, and code_challenge.

3PortTask shows consent screen. User reviews requested permissions and approves or denies.

4PortTask redirects back to your redirect_uri with an authorization code and the state parameter.

5Your server exchanges the code for tokens by sending the code, client_secret, and code_verifier to the token endpoint.

6PortTask returns access_token and refresh_token. Store tokens securely and use the access_token for API requests.

Step 1: Redirect to Authorization

Authorization Request

GET https://app.porttask.com/oauth/authorize?
  client_id=pt_client_aBcDeFgHiJkLmNoPqRsTu
  &redirect_uri=https://yourapp.com/callback
  &response_type=code
  &scope=port-calls:read vessels:read
  &state=random_csrf_token
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256

Step 2: Exchange Code for Tokens

Token Exchange Request

POST https://app.porttask.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&client_id=pt_client_aBcDeFgHiJkLmNoPqRsTu
&client_secret=pt_secret_YourClientSecret
&code=pt_code_receivedFromCallback
&redirect_uri=https://yourapp.com/callback
&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

Step 3: Receive Token Response

Token Response

{
  "access_token": "pt_access_eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "pt_refresh_dGhpcyBpcyBhIHJl...",
  "scope": "port-calls:read vessels:read"
}

Refreshing Access Tokens

Access tokens expire after 1 hour. Use the refresh token to obtain a new access token without requiring user re-authorization. Refresh tokens are valid for 30 days.

Refresh Token Request

POST https://app.porttask.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&client_id=pt_client_aBcDeFgHiJkLmNoPqRsTu
&client_secret=pt_secret_YourClientSecret
&refresh_token=pt_refresh_dGhpcyBpcyBhIHJl...

Access Token Lifetime

1 hour

Refresh Token Lifetime

30 days

Auth Code Lifetime

10 minutes

SDK Integration Examples

Our SDKs handle the OAuth flow for you, including PKCE, token storage, and automatic refresh.

TypeScript / Node.js

import { PortTaskOAuth } from '@porttask/sdk';

const oauth = new PortTaskOAuth({
  clientId: process.env.PORTTASK_CLIENT_ID,
  clientSecret: process.env.PORTTASK_CLIENT_SECRET,
  redirectUri: 'https://yourapp.com/callback',
});

// Step 1: Generate authorization URL
const authUrl = oauth.getAuthorizationUrl({
  scope: ['port-calls:read', 'vessels:read'],
  state: generateCSRFToken(),
});

// Step 2: Handle callback and exchange code for token
app.get('/callback', async (req, res) => {
  const { code, state } = req.query;
  verifyCSRFToken(state);

  const tokens = await oauth.exchangeCode(code);
  // tokens.accessToken, tokens.refreshToken

  // Step 3: Use the access token
  const client = oauth.getClient(tokens.accessToken);
  const portCalls = await client.portCalls.list();
});

Python

from porttask import PortTaskOAuth

oauth = PortTaskOAuth(
    client_id=os.environ["PORTTASK_CLIENT_ID"],
    client_secret=os.environ["PORTTASK_CLIENT_SECRET"],
    redirect_uri="https://yourapp.com/callback",
)

# Step 1: Generate authorization URL
auth_url = oauth.get_authorization_url(
    scope=["port-calls:read", "vessels:read"],
    state=generate_csrf_token(),
)

# Step 2: Exchange code for tokens (in your callback handler)
tokens = oauth.exchange_code(code=request.args["code"])

# Step 3: Make authenticated requests
client = oauth.get_client(tokens.access_token)
port_calls = client.port_calls.list()

View all SDK documentation

Scope Reference

Scopes define what your OAuth application can access. Request only the scopes your application needs -- users will see these permissions on the consent screen.

Scope	Description	Access Level
`read:port_calls`	Read port calls and related data	port_calls
`write:port_calls`	Create and update port calls	port_calls
`delete:port_calls`	Delete port calls	port_calls
`read:service_orders`	Read service orders	service_orders
`write:service_orders`	Create and update service orders	service_orders
`read:vendors`	Read vendor information	vendors
`write:vendors`	Manage vendor relationships	vendors
`read:vessels`	Read vessel information	vessels
`read:documents`	Read documents	documents
`write:documents`	Upload and manage documents	documents
`read:invoices`	Read invoices and billing	invoices
`write:invoices`	Create and manage invoices	invoices
`read:analytics`	Access analytics and reports	analytics
`ai:predictions`	Use AI prediction endpoints	predictions
`webhooks:manage`	Manage webhook subscriptions	manage
`admin`	Full administrative access	read

Grant Types Reference

Select the appropriate grant type based on your application architecture.

Authorization Code

PKCE Requiredauthorization_code

Standard OAuth 2.0 flow for web applications. Users authorize your app via the browser.

Best for: Web apps, mobile apps with backend

Client Credentials

client_credentials

Machine-to-machine authentication without user interaction. For server-side integrations.

Best for: Backend services, automated systems

Refresh Token

refresh_token

Exchange a refresh token for a new access token. Enables long-lived sessions.

Best for: Maintaining user sessions

Configuration Guide

Follow these steps to set up OAuth for your application.

Navigate to the PortTask Control Panel and create a new OAuth application. You will need to provide:

Application name -- displayed to users on the consent screen
Redirect URIs -- where users are sent after authorization (must be HTTPS in production)
Grant types -- authorization_code for user-facing apps, client_credentials for M2M
Scopes -- permissions your app will request from users

After registration, you will receive a Client ID and Client Secret. Store the client secret securely -- it is only shown once.

OAuth Endpoints

Endpoint	Method	Description
`/oauth/authorize`	GET	Starts the authorization flow. Redirect users here.
`/oauth/token`	POST	Exchange authorization code for tokens, or refresh an access token.
`/oauth/revoke`	POST	Revoke an access token or refresh token.
`/oauth/userinfo`	GET	Get information about the authenticated user.
`/.well-known/openid-configuration`	GET	OpenID Connect discovery document.

Security Best Practices

Always use PKCE with the Authorization Code flow, even for confidential clients. This prevents authorization code interception attacks.
Validate the state parameter on every callback to prevent CSRF attacks. Use a cryptographically random value.
Store tokens server-side. Never expose access tokens or refresh tokens in client-side JavaScript, URLs, or logs.
Use HTTPS for all redirect URIs in production. We reject non-HTTPS redirect URIs except for localhost during development.
Request minimal scopes. Only request permissions your application actually needs. Users are more likely to approve fewer permissions.
Rotate client secrets periodically. If a secret is compromised, rotate it immediately in the Control Panel.

Error Handling

OAuth errors follow the standard error response format defined in RFC 6749.

Error Code	Description	Resolution
`invalid_request`	Missing or malformed parameter	Check required parameters are present and correctly formatted
`unauthorized_client`	Client not authorized for this grant type	Verify grant type is enabled for your OAuth app
`access_denied`	User denied the authorization request	Show a message explaining why access is needed
`invalid_scope`	Requested scope exceeds allowed scopes	Only request scopes that are configured for your app
`invalid_grant`	Authorization code expired or already used	Codes expire after 10 minutes; restart the authorization flow
`invalid_client`	Client authentication failed	Verify client_id and client_secret are correct

Example Error Response

{
  "error": "invalid_grant",
  "error_description": "The authorization code has expired. Please restart the authorization flow."
}