> ## Documentation Index
> Fetch the complete documentation index at: https://developers.phonovation.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Obtain or refresh an OAuth access token
> Obtain OAuth tokens for integrations that require an OAuth lifecycle.
Most integrations should generate a reusable personal access token in the Phonovation application. Use this OAuth compatibility endpoint when your integration requires an OAuth token lifecycle.
## OpenAPI
````yaml openapi/phonovation-api.yaml POST /token
openapi: 3.1.2
info:
title: Phonovation SMS API
version: 1.0.0
summary: >-
Build SMS into your product, workflow, or platform with a straightforward,
developer-friendly API.
description: >
**Build fast. Send with confidence.**
Add application-to-person (A2P) SMS to your product, workflow, or platform
with Phonovation. Use this API to send or schedule campaigns, track each
recipient in your own system, receive delivery updates, and review campaign
results.
From appointment reminders and service alerts to customer campaigns, you get
a clear integration path and the delivery visibility needed to keep every
message accountable.
## Account access
[Log in or create your Phonovation account](https://app.phonovation.com/) to
manage your messaging setup and developer settings.
A typical integration has three steps:
1. Authenticate with a bearer token.
2. Create a campaign with your message, sender ID, and recipients.
3. Track delivery through campaign summaries and signed webhooks.
## Authentication
Every campaign request needs a bearer token — the credential that tells
Phonovation which account is making the request. Add it to the
`Authorization` header:
`Authorization: Bearer `
### Recommended: a UI-generated Personal Access Token
For most integrations, the simplest and preferred option is a Phonovation
Personal Access Token (PAT) generated in the Phonovation UI. PATs begin with
`phv_pat_`; keep the casing exactly as shown when sending one:
`Authorization: Bearer phv_pat_...`
[Generate and manage your
PATs](https://app.phonovation.com/developer?tab=pat-tokens)
in the Phonovation developer settings.
Generate the PAT once, store it securely, and reuse it for your API
requests.
**You do not need to obtain or refresh an OAuth token every time you send an
SMS.** Replace the PAT only when it expires, is revoked, or you
intentionally
rotate it.
### Optional: OAuth access tokens
OAuth/OIDC JWT access tokens remain available for integrations that
specifically
require an OAuth token lifecycle. The `/token` endpoint can exchange user
credentials for an access token and refresh token, or exchange a refresh
token
for a new access token.
Even when using OAuth, request an access token once and reuse it until it is
close
to expiry. Use the refresh token to obtain the next access token — do not
request
a new token before every SMS.
## Campaign processing
Campaign requests are accepted and queued for background processing. A
successful
request returns `202 Accepted` with the campaign ID.
A `202` response confirms receipt, not final campaign creation. Allow time
for
processing before requesting the campaign summary.
## Scheduling timezone
The `sendAt` value is always interpreted as Irish local time in the
`Europe/Dublin` timezone. Phonovation does not interpret it as UTC and does
not use the timezone of the caller, server, account, or recipient.
Do not include a timezone designator such as `Z` or a numeric UTC offset.
International integrations must convert the intended send time to Irish
local time before making the request. Ireland observes daylight saving time,
so use a timezone-aware library and the `Europe/Dublin` timezone instead of
a fixed UTC offset.
servers:
- url: https://api.phonovation.com
description: Phonovation production API
- url: https://auth.phonovation.com
description: Phonovation authentication server
security:
- BearerAuth: []
tags:
- name: Authentication
description: >-
Use a UI-generated PAT where possible, or obtain OAuth tokens for
integrations that require them.
- name: Health
description: Check whether the Phonovation API is available and responding.
- name: Campaigns
description: Send now or schedule ahead, then track delivery from one integration.
paths:
/token:
post:
tags:
- Authentication
summary: Obtain or refresh an OAuth access token
description: >
This endpoint is an optional OAuth route for integrations that need an
access
token and refresh-token lifecycle.
**For most integrations, use a Personal Access Token generated in the
Phonovation UI instead.** A PAT can be reused across SMS requests, so
you do
not need to call this endpoint, generate an OAuth token, or refresh a
token
every time you send a message.
If your integration does require OAuth, send this request as
`application/x-www-form-urlencoded`. The OAuth client ID is
`messaging-api`.
Supported grants:
- `password`: exchange a Phonovation username and password for an access
token
and refresh token. This compatibility flow must be enabled for the
`messaging-api` client.
- `refresh_token`: exchange a valid refresh token for a new access token
without resending the username and password.
Reuse the returned access token until it is close to expiry, then use
the
refresh token. Do not request a new access token for each SMS.
operationId: obtainAccessToken
requestBody:
required: true
description: OAuth credentials or a refresh token, encoded as form fields.
content:
application/x-www-form-urlencoded:
schema:
oneOf:
- $ref: '#/components/schemas/PasswordGrantRequest'
- $ref: '#/components/schemas/RefreshTokenGrantRequest'
examples:
passwordGrant:
summary: Obtain tokens with user credentials
value:
client_id: messaging-api
grant_type: password
username: user@example.com
password: your-password
refreshTokenGrant:
summary: Refresh an access token
value:
client_id: messaging-api
grant_type: refresh_token
refresh_token: your-refresh-token
responses:
'200':
description: OAuth tokens issued successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/TokenResponse'
example:
access_token: eyJhbGciOi...
expires_in: 300
refresh_expires_in: 1800
refresh_token: eyJhbGciOi...
token_type: Bearer
not-before-policy: 0
session_state: 11111111-2222-3333-4444-555555555555
scope: openid
'400':
description: The credentials, grant, or refresh token were missing or invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/OAuthError'
examples:
invalidGrant:
summary: Invalid credentials or refresh token
value:
error: invalid_grant
error_description: Invalid user credentials
'401':
description: >-
OAuth client authentication failed, if client authentication is
required.
content:
application/json:
schema:
$ref: '#/components/schemas/OAuthError'
security: []
servers:
- url: https://auth.phonovation.com
description: Phonovation authentication server
components:
schemas:
PasswordGrantRequest:
type: object
title: Password Grant Request
description: >
OAuth compatibility request that exchanges Phonovation user credentials
for
an access token and refresh token. Most integrations should use a
UI-generated
PAT instead.
required:
- client_id
- grant_type
- username
- password
properties:
client_id:
type: string
enum:
- messaging-api
default: messaging-api
description: OAuth client identifier. Use `messaging-api`.
grant_type:
type: string
enum:
- password
description: Use `password` to exchange user credentials for OAuth tokens.
username:
type: string
description: Your Phonovation username.
password:
type: string
format: password
writeOnly: true
description: Your Phonovation password.
RefreshTokenGrantRequest:
type: object
title: Refresh Token Grant Request
description: >
Exchanges a valid refresh token for a new OAuth access token. Reuse each
access token until it is close to expiry rather than refreshing before
every
SMS request.
required:
- client_id
- grant_type
- refresh_token
properties:
client_id:
type: string
enum:
- messaging-api
default: messaging-api
description: OAuth client identifier. Use `messaging-api`.
grant_type:
type: string
enum:
- refresh_token
description: Use `refresh_token` to obtain a new OAuth access token.
refresh_token:
type: string
writeOnly: true
description: Refresh token returned by an earlier successful token request.
TokenResponse:
type: object
title: OAuth Token Response
description: OAuth tokens and their lifetimes.
required:
- access_token
- expires_in
- token_type
properties:
access_token:
type: string
description: >-
OAuth access token to reuse in the `Authorization` header until it
is close to expiry.
expires_in:
type: integer
format: int32
description: Access-token lifetime in seconds.
refresh_expires_in:
type: integer
format: int32
description: Refresh-token lifetime in seconds, when returned.
refresh_token:
type: string
description: >-
Token used to obtain a new access token without resending user
credentials.
token_type:
type: string
description: Authorization scheme for the access token.
examples:
- Bearer
id_token:
type: string
description: >-
OpenID Connect ID token, when returned for the requested scope or
flow.
not-before-policy:
type: integer
format: int32
description: Authentication not-before policy value, when returned.
session_state:
type: string
description: Authentication session identifier, when returned.
scope:
type: string
description: Space-separated OAuth scopes granted to the token, when returned.
additionalProperties: true
OAuthError:
type: object
title: OAuth Error
description: Error returned when an OAuth token request cannot be completed.
required:
- error
properties:
error:
type: string
description: Machine-readable OAuth error code.
error_description:
type: string
description: Human-readable detail to help diagnose the failed token request.
additionalProperties: true
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: >
A UI-generated Phonovation Personal Access Token (PAT) is the
recommended
option for most integrations. OAuth/OIDC JWT access tokens are also
accepted
when an OAuth lifecycle is required.
Send either token as:
`Authorization: Bearer `
PAT values begin with `phv_pat_`. Generate a PAT once in the Phonovation
UI,
store it securely, and reuse it across requests. You do not need to
generate
or refresh a token for every SMS. Preserve the exact casing in
`Bearer phv_pat_...`.
````