Authentication & Authorization

The Hey Jodie API uses OAuth 2.0 for authentication. This is a widely-adopted industry standard that provides secure, token-based access to your data without requiring you to share your password.

What is OAuth 2.0?

OAuth 2.0 is an authorization framework that enables applications to obtain limited access to user accounts. Instead of using a username and password for each API request, you obtain an access token that represents your authorization to access the API.

Key Benefits:

• Security: Your password is never shared with the API
• Revocable: Tokens can be revoked without changing your password
• Scoped Access: Tokens can be limited to specific permissions
• Time-Limited: Tokens can expire automatically for enhanced security

Getting Your Access Token

To interact with the API, you need an OAuth 2.0 access token. The exact process for obtaining this token depends on your Hey Jodie account configuration and may involve:

1. Application Registration: Register your application to receive OAuth client credentials
2. Authorization Request: Request authorization from the Hey Jodie authorization server
3. Token Exchange: Exchange the authorization code for an access token
4. Token Storage: Securely store the token for use in API requests

Contact your Hey Jodie administrator or support team for specific instructions on obtaining your OAuth token, as the process may vary based on your account configuration.

Using Your Access Token

Once you have an access token, include it in the Authorization header of every API request:

Authorization: Bearer YOUR_ACCESS_TOKEN

Replace YOUR_ACCESS_TOKEN with your actual token. This header authenticates you and authorizes the request.

Example Request:

GET /api/oauth/me HTTP/1.1
Host: app.heyjodie.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...

Token Security Best Practices

• Use HTTPS Only: Always use HTTPS to prevent token interception
• Secure Storage: Store tokens securely (encrypted databases, secure environment variables)
• Never Expose Tokens: Don’t commit tokens to version control or log them
• Rotate Regularly: Implement token rotation policies for enhanced security
• Monitor Usage: Track token usage to detect unauthorized access

Token Lifecycle

Access tokens have a limited lifetime for security reasons:

• Expiration: Tokens expire after a predetermined period (contact support for specifics)
• Refresh Tokens: Some OAuth configurations provide refresh tokens to obtain new access tokens
• Revocation: Tokens can be revoked manually if compromised
• Reauthorization: Expired tokens require reauthorization to obtain new ones

When a token expires, you’ll receive a 401 Unauthorized response. Implement proper error handling to detect this and obtain a new token.

Account Requirements

Not all Hey Jodie accounts can access the OAuth API. The following requirements apply:

User Role Restriction

Only accounts with USER role can access OAuth endpoints.

This restriction exists because:

• Admin accounts have elevated privileges that should not be exposed via API
• The API is designed for programmatic access to call data, not administrative functions
• This separation follows the principle of least privilege for enhanced security

If you attempt to use an admin account, you’ll receive a 403 Forbidden error.

Company Association

Every API token is associated with a specific company in the Hey Jodie system. This means:

• You can only access calls and data for your own company
• Data from other companies is completely isolated and inaccessible
• This multi-tenant architecture ensures data privacy and security

Authentication Errors

401 Unauthorized - Invalid or Missing Token

Cause: The access token is missing, invalid, expired, or revoked.

{
  "message": "Unauthenticated."
}

How to Resolve:

• Verify the token is included in the Authorization header
• Check that the token hasn’t expired
• Ensure the token format is correct: Bearer [token]
• If expired, obtain a new token through the OAuth flow
• Verify there are no extra spaces or formatting issues

403 Forbidden - Wrong Account Type

Cause: You’re using an admin account, which cannot access OAuth endpoints.

{
  "message": "OAuth2 access is restricted to user accounts only."
}

How to Resolve:

• Use a USER role account instead of an admin account
• Create a dedicated service account with USER role for API access
• Contact your administrator if you need help creating the appropriate account

Testing Your Authentication

To verify your authentication is working, make a request to the user information endpoint:

curl -X GET "https://app.heyjodie.com/api/oauth/me" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

If successful, you’ll receive your user information. If not, check the error response and follow the troubleshooting steps above.