REST OAuth API for Secure SMS Integration

Use the SMSGatewayCenter REST OAuth API when you want customers, team members, or connected apps to sign in with their SMS Gateway Center account and authorize your application to send SMS, read templates, check balance, and use other SMS REST APIs on their behalf. This guide explains the public OAuth 2.0 flow with PKCE for developers building web apps, automation platforms, AI connectors, and custom integrations in India and worldwide.

OAuth is ideal when you do not want users to paste API keys manually. After sign-in, your application receives short-lived and refreshable tokens that can be used with the same SMS REST endpoints documented in this developer portal.

Overview

The REST OAuth API follows the OAuth 2.0 Authorization Code flow with PKCE (Proof Key for Code Exchange). This is the recommended approach for web applications, SaaS products, automation tools, and server-side integrations where your app opens a browser for user sign-in.

Important: A successful login does not return JSON directly to your app. The user browser is redirected to your registered redirect URI (callback URL) with an authorization code. Your application must handle that callback and call the token endpoint to obtain the access token.

If you only need direct server-to-server access with your own account credentials, you can also use the standard API authentication guide with API key or userid and password.

Authorization flow

1. Your application redirects the user to the authorize endpoint with client_id, redirect_uri, state, and PKCE values.
2. The user signs in on the SMS Gateway Center authorization page. If OTP login is enabled on the account, the user completes OTP or Google Authenticator verification.
3. After successful authentication, the platform issues an authorization code and redirects the browser to your callback URL:
   https://your-app.com/oauth/callback?code=AUTHORIZATION_CODE&state=YOUR_STATE
4. Your callback handler validates state, then sends a server-side POST request to the token endpoint with the code, code_verifier, client_id, client_secret, and the same redirect_uri.
5. The token response returns access_token, refresh_token, and username. Use the access token when calling SMS REST APIs on behalf of the signed-in user.

Prerequisites

• OAuth client registration: Contact our support team to register your application. You will receive a client_id, client_secret, and one or more allowed redirect_uri values.
• HTTPS callback URL: Production callback URLs must use HTTPS. The redirect URI in your authorize request must exactly match a registered callback URL.
• PKCE support: Generate a code_verifier and code_challenge for each authorization attempt. Only S256 challenge method is supported.
• State parameter: Generate a random state value per request and validate it in your callback handler to prevent CSRF attacks.
• Active SMS Gateway Center account: The signing-in user must have a valid account with SMS API access enabled.

API endpoints

Step 1: Start authorization

Redirect the user browser to the authorize endpoint with these query parameters:

Example authorize request:

curl -i -G "https://unify.smsgateway.center/rest/oauth/v1/authorize" \--data-urlencode "response_type=code" \--data-urlencode "client_id=YOUR_CLIENT_ID" \--data-urlencode "redirect_uri=https://your-app.com/oauth/callback" \--data-urlencode "state=random-state-value" \--data-urlencode "code_challenge=YOUR_CODE_CHALLENGE" \--data-urlencode "code_challenge_method=S256" \--data-urlencode "prompt=login"

A valid request returns the HTML sign-in page (HTTP 200). The user completes login on that page.

Step 2: Handle the callback redirect

After successful authentication, the platform redirects the user browser to your registered redirect_uri with these query parameters:

Example successful redirect:

HTTP/1.1 302 Found
Location: https://your-app.com/oauth/callback?code=AUTHORIZATION_CODE&state=random-state-value

Your callback handler must:

1. Verify that state matches the value stored for this authorization attempt.
2. Read the code query parameter.
3. Call the token endpoint from your server only. Never exchange the code from browser JavaScript.
4. Store tokens securely and redirect the user to your application success page.

Note: Authorization codes expire quickly. Exchange the code as soon as your callback receives it.

Step 3: Exchange code for tokens

Send a server-side POST request to the token endpoint using application/x-www-form-urlencoded:

curl -s -X POST "https://unify.smsgateway.center/rest/oauth/v1/token" \-H "Content-Type: application/x-www-form-urlencoded" \--data-urlencode "grant_type=authorization_code" \--data-urlencode "client_id=YOUR_CLIENT_ID" \--data-urlencode "client_secret=YOUR_CLIENT_SECRET" \--data-urlencode "code=AUTHORIZATION_CODE_FROM_CALLBACK" \--data-urlencode "redirect_uri=https://your-app.com/oauth/callback" \--data-urlencode "code_verifier=YOUR_CODE_VERIFIER"

Example success response (HTTP 200):

{
  "access_token": "your-sms-api-key",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "opaque-refresh-token-value",
  "username": "your-user-id",
  "scope": ""
}

The access_token authorizes SMS REST API calls on behalf of the signed-in user. The username value is the SMS Gateway Center user ID required on SMS API requests.

Token storage and lifetimes

When a user disconnects your app or logs out, call the revoke endpoint with the refresh token to end the authorized session.

Step 4: Refresh an access token

Before the access token expires, or after you receive an authentication error from SMS APIs, request a new access token using the stored refresh token:

curl -s -X POST "https://unify.smsgateway.center/rest/oauth/v1/token" \-H "Content-Type: application/x-www-form-urlencoded" \--data-urlencode "grant_type=refresh_token" \--data-urlencode "client_id=YOUR_CLIENT_ID" \--data-urlencode "client_secret=YOUR_CLIENT_SECRET" \--data-urlencode "refresh_token=YOUR_REFRESH_TOKEN"

Example refresh success response (HTTP 200):

{
  "access_token": "your-sms-api-key",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "",
  "username": "your-user-id",
  "scope": ""
}

On refresh, a new access_token is returned. The same refresh_token remains valid until it expires or is revoked.

If refresh fails with invalid_grant, the refresh token has expired or been revoked. Redirect the user through the authorize flow again.

Step 5: Revoke tokens

Revoke the refresh token when the user logs out of your application or disconnects the integration:

curl -s -X POST "https://unify.smsgateway.center/rest/oauth/v1/revoke" \-H "Content-Type: application/x-www-form-urlencoded" \--data-urlencode "client_id=YOUR_CLIENT_ID" \--data-urlencode "client_secret=YOUR_CLIENT_SECRET" \--data-urlencode "refresh_token=YOUR_REFRESH_TOKEN"

Example revoke success response (HTTP 200):

{
  "revoked": true
}

Step 6: Call SMS APIs after OAuth

After OAuth completes, use these two values together on every SMS REST API call:

Important: OAuth does not replace the SMS API request format. You still call the same SMS REST endpoints documented in this developer portal. OAuth only replaces manual password or API key entry with a user sign-in flow.

Always include userid=USERNAME_FROM_TOKEN_RESPONSE and output=json in the SMS API request.

Example: Check SMS balance

curl -s -G "https://unify.smsgateway.center/SMSApi/account/readstatus" \--data-urlencode "userid=YOUR_USERNAME" \--data-urlencode "output=json" \-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Example: Read SMS templates

curl -s -G "https://unify.smsgateway.center/SMSApi/template/read" \--data-urlencode "userid=YOUR_USERNAME" \--data-urlencode "output=json" \-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

To fetch one template by ID, add id=TEMPLATE_ID to the query string.

Example: Send SMS (quick send)

curl -s -X POST "https://unify.smsgateway.center/SMSApi/send" \-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \-H "Content-Type: application/x-www-form-urlencoded" \--data-urlencode "userid=YOUR_USERNAME" \--data-urlencode "output=json" \--data-urlencode "sendMethod=quick" \--data-urlencode "mobile=919999999999" \--data-urlencode "senderid=YOUR_SENDER_ID" \--data-urlencode "msg=Your order is ready." \--data-urlencode "msgType=text" \--data-urlencode "duplicatecheck=true"

If your account uses DLT in India, include the approved dltTemplateId and dltEntityId values documented in the SMS API section. See also our Send SMS API guide for additional parameters.

Token introspection (optional)

If your application receives only a bearer token and needs to resolve the account username before calling SMS APIs, use the introspection endpoint:

curl -s -X POST "https://unify.smsgateway.center/rest/oauth/v1/introspect" \-H "Content-Type: application/x-www-form-urlencoded" \--data-urlencode "token=YOUR_ACCESS_TOKEN"

Example active token response:

{
  "active": true,
  "username": "your-user-id",
  "token_type": "Bearer"
}

Use the returned username as the SMS API userid parameter.

Third-party integrations

All OAuth-connected apps follow the same pattern after sign-in:

1. Complete the OAuth authorize and token exchange on your server.
2. Store access_token, refresh_token, and username securely.
3. Refresh the access token before it expires.
4. Call SMS APIs with userid=username and the current access token as bearer or apikey header.

OTP and two-factor login during OAuth

If the signing-in user has OTP login enabled, the authorization page follows the same rules as the standard account login:

1. User enters User ID and password.
2. If OTP is required, the user selects an OTP medium such as Email, SMS, WhatsApp, or Google Authenticator when configured.
3. User enters the OTP code.
4. After OTP verification succeeds, the platform redirects to your callback URL with the authorization code.

If OTP is not enabled on the account, successful password validation redirects directly to your callback URL.

Security requirements

• Always use HTTPS for production callback URLs.
• Never expose client_secret or tokens in client-side JavaScript or mobile app packages.
• Validate state on every callback.
• Store code_verifier securely until the token exchange completes.
• Exchange authorization codes only from your server.
• Use prompt=login when you need to force a fresh sign-in.
• Revoke tokens when the user disconnects your application.

Common errors

OAuth error responses use this JSON format:

{
  "error": "error_code",
  "error_description": "Human readable message."
}

If token exchange fails with invalid_grant immediately after login, verify that your callback URL matches the registered redirect URI exactly, that the authorization code was exchanged promptly, and that your PKCE code_verifier matches the original challenge.

Frequently asked questions

Need OAuth client credentials? Contact our support team with your application name, callback URL, and use case. You can also explore the rest of our SMS API documentation for send, templates, reports, and more.

Unlock Real-Time Messaging – Integrate Today!

Try Our API in a Sandbox Environment Before Going Live!

Join Thousands of Developers – Try Our API Now!

Get in touchSign up