Authentication

The Pulse API uses JWT-based authentication. All authenticated endpoints require a valid access token in the Authorization header.

Endpoints

POST /v1/auth/social/authenticate
GET  /v1/auth/token/verify
POST /v1/auth/token/refresh

---

Social Authenticate

Authenticates a user via Google OAuth, validates the ID token, and returns access and refresh tokens.

Endpoint: POST /v1/auth/social/authenticate

Request Headers:

Header	Value
Content-Type	application/json

Request Body:

Field	Type	Required	Description
responseType	string	✅ Yes	Response type (e.g., "token")
grantType	string	✅ Yes	Grant type (e.g., "authorization_code")
identifier	string	✅ Yes	Google ID token from OAuth flow
idProvider	string	✅ Yes	Identity provider (e.g., "google")
resources	string[]	✅ Yes	Array of resource scopes (e.g., ["pulse"])

Example Request:

POST /v1/auth/social/authenticate
Content-Type: application/json

{
  "responseType": "token",
  "grantType": "authorization_code",
  "identifier": "google-id-token",
  "idProvider": "google",
  "resources": ["pulse"]
}

Response:

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 3600,
  "idToken": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjEyMzQ1NiJ9...",
  "refreshToken": "refresh-token-12345",
  "tokenType": "Bearer"
}

Response Fields:

Field	Type	Description
accessToken	string	JWT access token for API authentication
expiresIn	number	Token expiration time in seconds
idToken	string	Identity token containing user information
refreshToken	string	Token used to obtain new access tokens
tokenType	string	Token type (always "Bearer")

---

Verify Auth Token

Verifies if the provided authorization token is valid and not expired.

Endpoint: GET /v1/auth/token/verify

Request Headers:

Header	Value
authorization	Bearer {accessToken}

Example Request:

GET /v1/auth/token/verify
authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Response:

{
  "isAuthTokenValid": true
}

Response Fields:

Field	Type	Description
isAuthTokenValid	boolean	true if token is valid, false otherwise

---

Refresh Token

Obtains a new access token using a valid refresh token. Use this endpoint when your access token has expired.

Endpoint: POST /v1/auth/token/refresh

Request Headers:

Header	Value
Content-Type	application/json

Request Body:

Field	Type	Required	Description
refreshToken	string	✅ Yes	Refresh token obtained from initial authentication

Example Request:

POST /v1/auth/token/refresh
Content-Type: application/json

{
  "refreshToken": "refresh-token-12345"
}

Response:

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 3600,
  "refreshToken": "refresh-token-12345",
  "tokenType": "Bearer"
}

Response Fields:

Field	Type	Description
accessToken	string	New JWT access token
expiresIn	number	Token expiration time in seconds
refreshToken	string	Refresh token (may be rotated)
tokenType	string	Token type (always "Bearer")