OAuth Quickstart — OnePageCRM Developers

Get credentials, complete the authorization flow, and make your first authenticated API call.

This guide walks through the full Authorization Code + PKCE flow. By the end you will have a working client_id, an access token, and a live API call.

Prerequisites: Decide whether your app is a public or confidential client before you start. Have your redirect URI ready.

Step 1: Get client credentials

Request client credentials from the OnePageCRM team. You’ll need:

Your application name — users see it on the consent screen
Your redirect URI(s): the URL OnePageCRM will redirect users to after they approve your app — https, or http://localhost / http://127.0.0.1 for development
Client type: public (browser/mobile app) or confidential (server-side app)

Registration is handled manually and can take a few days — request it before you plan to build. You’ll receive your client_id (and client_secret for confidential clients).

Step 2: Generate PKCE values

Before redirecting the user, generate a code_verifier and code_challenge. These are single-use values that tie the token exchange to this specific login attempt.

const array = new Uint8Array(64)
crypto.getRandomValues(array)
const codeVerifier = btoa(String.fromCharCode(...array))
.replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '')

const encoded = new TextEncoder().encode(codeVerifier)
const digest = await crypto.subtle.digest('SHA-256', encoded)
const codeChallenge = btoa(String.fromCharCode(...new Uint8Array(digest)))
.replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '')

// Store for use in the callback
sessionStorage.setItem('code_verifier', codeVerifier)

import secrets
import hashlib
import base64

code_verifier = secrets.token_urlsafe(64)
digest = hashlib.sha256(code_verifier.encode()).digest()
code_challenge = base64.urlsafe_b64encode(digest).rstrip(b'=').decode()

require 'securerandom'
require 'digest'
require 'base64'

code_verifier = Base64.urlsafe_encode64(SecureRandom.random_bytes(64), padding: false)
code_challenge = Base64.urlsafe_encode64(Digest::SHA256.digest(code_verifier), padding: false)

import java.security.MessageDigest
import java.security.SecureRandom
import android.util.Base64

val bytes = ByteArray(64).also { SecureRandom().nextBytes(it) }
val codeVerifier = Base64.encodeToString(bytes, Base64.URL_SAFE or Base64.NO_WRAP or Base64.NO_PADDING)

val digest = MessageDigest.getInstance("SHA-256").digest(codeVerifier.toByteArray())
val codeChallenge = Base64.encodeToString(digest, Base64.URL_SAFE or Base64.NO_WRAP or Base64.NO_PADDING)

import CryptoKit
import Foundation
import Security

var bytes = [UInt8](repeating: 0, count: 64)
_ = SecRandomCopyBytes(kSecRandomDefault, bytes.count, &bytes)
let codeVerifier = Data(bytes).base64EncodedString()
  .replacingOccurrences(of: "+", with: "-")
  .replacingOccurrences(of: "/", with: "_")
  .replacingOccurrences(of: "=", with: "")

let digest = SHA256.hash(data: Data(codeVerifier.utf8))
let codeChallenge = Data(digest).base64EncodedString()
  .replacingOccurrences(of: "+", with: "-")
  .replacingOccurrences(of: "/", with: "_")
  .replacingOccurrences(of: "=", with: "")

Step 3: Redirect the user to OnePageCRM

Send the user to the authorization endpoint. On mobile, use the platform’s secure browser API, not a WebView.

const state = crypto.randomUUID()
sessionStorage.setItem('oauth_state', state)

const params = new URLSearchParams({
response_type: 'code',
client_id: 'YOUR_CLIENT_ID',
redirect_uri: 'https://myapp.example.com/callback',
scope: 'crm.readonly',
state,
code_challenge: codeChallenge,
code_challenge_method: 'S256',
})

window.location.href = `https://secure.onepagecrm.com/oauth/authorize?${params}`

import secrets
from urllib.parse import urlencode

state = secrets.token_urlsafe(32)
# Store state in session: session['oauth_state'] = state

params = urlencode({
  'response_type': 'code',
  'client_id': 'YOUR_CLIENT_ID',
  'redirect_uri': 'https://myapp.example.com/callback',
  'scope': 'crm.readonly',
  'state': state,
  'code_challenge': code_challenge,
  'code_challenge_method': 'S256',
})

# Flask/Django: redirect to this URL
auth_url = f'https://secure.onepagecrm.com/oauth/authorize?{params}'

require 'securerandom'
require 'uri'

state = SecureRandom.urlsafe_base64(32)
# Store in session: session[:oauth_state] = state

params = URI.encode_www_form(
response_type: 'code',
client_id: 'YOUR_CLIENT_ID',
redirect_uri: 'https://myapp.example.com/callback',
scope: 'crm.readonly',
state: state,
code_challenge: code_challenge,
code_challenge_method: 'S256'
)

# Rails: redirect_to
auth_url = "https://secure.onepagecrm.com/oauth/authorize?#{params}"

// Uses AppAuth for Android — recommended for secure mobile OAuth
// Add to build.gradle: implementation 'net.openid:appauth:0.11.1'
import android.net.Uri
import net.openid.appauth.*

val serviceConfig = AuthorizationServiceConfiguration(
  Uri.parse("https://secure.onepagecrm.com/oauth/authorize"),
  Uri.parse("https://secure.onepagecrm.com/oauth/token")
)

val authRequest = AuthorizationRequest.Builder(
  serviceConfig,
  "YOUR_CLIENT_ID",
  ResponseTypeValues.CODE,
  // Must be https (Android App Link) — custom schemes like
  // myapp:// are rejected at registration.
  Uri.parse("https://myapp.example.com/oauth/callback")
)
  .setScope("crm.readonly")
  .setCodeVerifier(codeVerifier, codeChallenge, "S256")
  .build()

val authService = AuthorizationService(this)
val intent = authService.getAuthorizationRequestIntent(authRequest)
startActivityForResult(intent, RC_AUTH)

// Uses ASWebAuthenticationSession — Apple's secure OAuth browser
import AuthenticationServices

let state = UUID().uuidString
var components = URLComponents(string: "https://secure.onepagecrm.com/oauth/authorize")!
components.queryItems = [
  .init(name: "response_type", value: "code"),
  .init(name: "client_id",     value: "YOUR_CLIENT_ID"),
  // Must be https (universal link) — custom schemes like
  // myapp:// are rejected at registration.
  .init(name: "redirect_uri",  value: "https://myapp.example.com/oauth/callback"),
  .init(name: "scope",         value: "crm.readonly"),
  .init(name: "state",         value: state),
  .init(name: "code_challenge", value: codeChallenge),
  .init(name: "code_challenge_method", value: "S256"),
]

let session = ASWebAuthenticationSession(
  url: components.url!,
  callback: .https(host: "myapp.example.com", path: "/oauth/callback")  // iOS 17.4+
) { callbackURL, error in
  guard let url = callbackURL, error == nil else { return }
  // Extract code and state from url, then exchange for tokens
}
session.presentationContextProvider = self
session.start()

Step 4: Exchange the code for tokens

After the user approves, OnePageCRM redirects back with ?code=...&state=.... Verify the state, then exchange the code immediately. It expires in 10 minutes and is single-use.

curl -X POST https://secure.onepagecrm.com/oauth/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=authorization_code" \
-d "code=AUTH_CODE" \
-d "redirect_uri=https://myapp.example.com/callback" \
-d "client_id=YOUR_CLIENT_ID" \
-d "code_verifier=YOUR_CODE_VERIFIER"

const params = new URLSearchParams(window.location.search)

if (params.get('state') !== sessionStorage.getItem('oauth_state')) {
throw new Error('State mismatch — possible CSRF attack')
}

const codeVerifier = sessionStorage.getItem('code_verifier')
sessionStorage.removeItem('code_verifier')
sessionStorage.removeItem('oauth_state')

const response = await fetch('https://secure.onepagecrm.com/oauth/token', {
method: 'POST',
headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
body: new URLSearchParams({
  grant_type: 'authorization_code',
  code: params.get('code'),
  redirect_uri: 'https://myapp.example.com/callback',
  client_id: 'YOUR_CLIENT_ID',
  code_verifier: codeVerifier,
}),
})
const tokens = await response.json()

import requests

# Verify state matches what you stored before the redirect
assert request.args['state'] == session['oauth_state'], 'State mismatch'

response = requests.post(
  'https://secure.onepagecrm.com/oauth/token',
  data={
      'grant_type': 'authorization_code',
      'code': request.args['code'],
      'redirect_uri': 'https://myapp.example.com/callback',
      'client_id': 'YOUR_CLIENT_ID',
      'code_verifier': session['code_verifier'],
  }
)
tokens = response.json()

require 'net/http'
require 'json'

# Verify state matches what you stored before the redirect
raise 'State mismatch' unless params[:state] == session[:oauth_state]

uri = URI('https://secure.onepagecrm.com/oauth/token')
response = Net::HTTP.post_form(uri, {
grant_type: 'authorization_code',
code: params[:code],
redirect_uri: 'https://myapp.example.com/callback',
client_id: 'YOUR_CLIENT_ID',
code_verifier: session[:code_verifier]
})
tokens = JSON.parse(response.body)

import android.net.Uri
import net.openid.appauth.*
import okhttp3.*

// AppAuth handles the callback and code exchange
override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
  if (requestCode == RC_AUTH) {
      val resp = AuthorizationResponse.fromIntent(data!!)
      val ex = AuthorizationException.fromIntent(data)

      if (resp != null) {
          val authService = AuthorizationService(this)
          authService.performTokenRequest(resp.createTokenExchangeRequest()) { tokenResp, ex ->
              if (tokenResp != null) {
                  val accessToken = tokenResp.accessToken
                  val refreshToken = tokenResp.refreshToken
              }
          }
      }
  }
}

import Foundation

var request = URLRequest(url: URL(string: "https://secure.onepagecrm.com/oauth/token")!)
request.httpMethod = "POST"
request.setValue("application/x-www-form-urlencoded", forHTTPHeaderField: "Content-Type")

let body = [
  "grant_type=authorization_code",
  "code=\(authCode)",
  "redirect_uri=https://myapp.example.com/oauth/callback",
  "client_id=YOUR_CLIENT_ID",
  "code_verifier=\(codeVerifier)",
].joined(separator: "&")
request.httpBody = body.data(using: .utf8)

let (data, _) = try await URLSession.shared.data(for: request)
let tokens = try JSONDecoder().decode(TokenResponse.self, from: data)

You receive:

{
  "access_token": "k2tV5VE1b3...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "crm.readonly",
  "aud": "https://app.onepagecrm.com",
  "refresh_token": "dGhpcyBpcyBh..."
}

The aud field is the CRM API base URL for this user’s account — it may be a regional host rather than app.onepagecrm.com. Always build API URLs from aud instead of hard-coding a host. Store access_token in memory and refresh_token securely.

Step 5: Make an API request

# Base URL comes from the token response's aud field
curl https://app.onepagecrm.com/api/v3/contacts.json \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

require 'net/http'
require 'json'

uri = URI("#{audience}/api/v3/contacts.json")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
request['Authorization'] = "Bearer #{access_token}"

response = http.request(request)
data = JSON.parse(response.body)

import okhttp3.*

val request = Request.Builder()
  .url("$audience/api/v3/contacts.json")
  .header("Authorization", "Bearer $accessToken")
  .build()

val response = OkHttpClient().newCall(request).execute()
val data = response.body!!.string()

var request = URLRequest(url: URL(string: "\(audience)/api/v3/contacts.json")!)
request.setValue("Bearer \(accessToken)", forHTTPHeaderField: "Authorization")

let (data, _) = try await URLSession.shared.data(for: request)
let contacts = try JSONDecoder().decode(ContactsResponse.self, from: data)

Step 6: Renew the access token

Access tokens expire after 60 minutes. Use the refresh token to get a new one silently, with no user interaction required.

curl -X POST https://secure.onepagecrm.com/oauth/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=refresh_token" \
-d "refresh_token=YOUR_REFRESH_TOKEN" \
-d "client_id=YOUR_CLIENT_ID"

const response = await fetch('https://secure.onepagecrm.com/oauth/token', {
method: 'POST',
headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
body: new URLSearchParams({
  grant_type: 'refresh_token',
  refresh_token: storedRefreshToken,
  client_id: 'YOUR_CLIENT_ID',
}),
})
const tokens = await response.json()
// Always save the new refresh token — the old one is now invalid
storedRefreshToken = tokens.refresh_token

response = requests.post(
  'https://secure.onepagecrm.com/oauth/token',
  data={
      'grant_type': 'refresh_token',
      'refresh_token': stored_refresh_token,
      'client_id': 'YOUR_CLIENT_ID',
  }
)
tokens = response.json()
stored_refresh_token = tokens['refresh_token']  # always save the new one

response = Net::HTTP.post_form(
URI('https://secure.onepagecrm.com/oauth/token'),
grant_type: 'refresh_token',
refresh_token: stored_refresh_token,
client_id: 'YOUR_CLIENT_ID'
)
tokens = JSON.parse(response.body)
stored_refresh_token = tokens['refresh_token']  # always save the new one

val body = FormBody.Builder()
  .add("grant_type", "refresh_token")
  .add("refresh_token", storedRefreshToken)
  .add("client_id", "YOUR_CLIENT_ID")
  .build()

val request = Request.Builder()
  .url("https://secure.onepagecrm.com/oauth/token")
  .post(body)
  .build()

val response = OkHttpClient().newCall(request).execute()
val tokens = JSONObject(response.body!!.string())
storedRefreshToken = tokens.getString("refresh_token")  // always save the new one

var request = URLRequest(url: URL(string: "https://secure.onepagecrm.com/oauth/token")!)
request.httpMethod = "POST"
request.setValue("application/x-www-form-urlencoded", forHTTPHeaderField: "Content-Type")
request.httpBody = "grant_type=refresh_token&refresh_token=\(storedRefreshToken)&client_id=YOUR_CLIENT_ID"
  .data(using: .utf8)

let (data, _) = try await URLSession.shared.data(for: request)
let tokens = try JSONDecoder().decode(TokenResponse.self, from: data)
storedRefreshToken = tokens.refreshToken  // always save the new one

Public clients: Every refresh response includes a new refresh token. Always replace the old one. Reusing a rotated token revokes the entire session.

Next steps

Reference: every endpoint, parameter, error code, and security detail.