Authentication

tPay365 supports two authentication methods: OAuth 2.0 for user-facing applications and scoped API keys for server-to-server communication.

OAuth 2.0 Flow

Use the Authorization Code flow for applications that act on behalf of users. Redirect users to the authorization endpoint, then exchange the code for tokens.

1. Authorization Request

Redirect user to authorize

http

GET /api/v1/auth/authorize?
  client_id=your_client_id
  &redirect_uri=https://yourapp.com/callback
  &response_type=code
  &scope=read:profile write:paycheck
  &state=random_csrf_token

2. Token Exchange

Exchange code for tokens

http

POST /api/v1/auth/token HTTP/1.1
Host: api.tpay365.com
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "code": "auth_code_from_redirect",
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "redirect_uri": "https://yourapp.com/callback"
}

API Keys

For server-to-server communication, use scoped API keys. Keys are prefixed with their environment: sk_live_ for production and sk_test_ for sandbox.

API key authentication

http

GET /api/v1/engine/paycheck/calculate HTTP/1.1
Host: api.tpay365.com
Authorization: Bearer sk_live_abc123def456

Never share production keys

Production API keys have access to real financial data. Rotate keys immediately if compromised. Use environment variables, never hard-code keys.

Scopes

API keys and OAuth tokens are scoped to limit access. Request only the scopes you need.

Parameter	Type	Required	Description
read:profile	scope	Optional	Read user profile and masked PII
write:paycheck	scope	Optional	Calculate and simulate paychecks
read:vault	scope	Optional	Retrieve masked vault data
write:vault	scope	Optional	Store new PII in the vault
admin:audit	scope	Optional	Access audit logs and system health

Token Refresh

Access tokens expire after 1 hour. Use the refresh token to get new access tokens without re-authenticating the user.

Refresh an access token

http

POST /api/v1/auth/token HTTP/1.1
Content-Type: application/json

{
  "grant_type": "refresh_token",
  "refresh_token": "rt_your_refresh_token",
  "client_id": "your_client_id"
}