OAuth2 is recommended only if you're developing an application where many different users on Acuity need to authenticate. Just looking to authenticate with one account? Use basic authentication instead.

OAuth2 is a standard for applications to grant authorization and exchange credentials for an API securely. It's the best option for allowing users of your application to connect to Acuity.

A user clicks a connect button in the client (your application) and is redirected to Acuity to enter their credentials. After authorizing your app, the user is redirected back to your application with an authorization code which you'll exchange for an API access token.

You'll need to register an Acuity OAuth2 client account to get started.

Integration

Once you've got a client account, you'll be ready to start integrating. The first step is to redirect the user to our authorization_url. It's usually a good idea to display a button like "Connect to Acuity."

https://acuityscheduling.com/oauth2/authorize?response_type=code&scope=api-v1&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI
var Acuity = require('acuityscheduling');
var express = require('express');
var port = process.env.PORT || 8000;

var app = express();

app.get('/', function (req, res) {
  var acuity = Acuity.oauth({
    clientId: 'YOUR_CLIENT_ID',
    clientSecret: 'YOUR_CLIENT_SECRET',
    redirectUri: 'YOUR_REDIRECT_URI'
  });
  acuity.authorizeRedirect(res, { scope: 'api-v1' });
});

app.listen(port, function () {
  console.log('Listening on %s', port);
}).on('error', function () {
  if (e) return console.error(e);
});
<?php
require_once('vendor/autoload.php');

$acuity = new AcuitySchedulingOAuth(array(
  'clientId' => 'YOUR_CLIENT_ID',
  'clientSecret' => 'YOUR_CLIENT_SECRET',
  'redirectUri' => 'YOUR_REDIRECT_URI'
));

$acuity->authorizeRedirect(array('scope' => 'api-v1'));

We'll verify your client_id, redirect_uri and scope, then display a login screen to the user allowing them to grant your application access to their Acuity account. Once the user is connected, Acuity will send them back to your redirect_uri with an authorization_code.

http://example.org/oauth2?code=AN_AUTHORIZATION_CODE

Your application then exchanges the authorization_code for an access_token allowing access to the Acuity API for that user's account. Data should be sent to our token endpoint as an application/x-www-form-urlencoded POST reqest.

curl https://acuityscheduling.com/oauth2/token \
 -d grant_type=authorization_code \
 -d code=AN_AUTHORIZATION_CODE \
 -d redirect_uri= YOUR_REDIRECT_URI \
 -d client_id=YOUR_CLIENT_ID \
 -d client_secret=YOUR_CLIENT_SECRET
var Acuity = require('acuityscheduling');
var express = require('express');
var url = require('url');
var port = process.env.PORT || 8000;

var app = express();

app.get(url.parse('YOUR_REDIRECT_URI').path, function (req, res) {
  var acuity = Acuity.oauth({
    clientId: 'YOUR_CLIENT_ID',
    clientSecret: 'YOUR_CLIENT_SECRET',
    redirectUri: 'YOUR_REDIRECT_URI'
  });
  acuity.requestAccessToken(req.query.code, function (err, tokenResponse) {
    if (err) return res.send(err);
    res.send(tokenResponse);
  });
});

app.listen(port, function () {
  console.log('Listening on %s', port);
}).on('error', function () {
  if (e) return console.error(e);
});
<?php
require_once('vendor/autoload.php');

$acuity = new AcuitySchedulingOAuth(array(
  'clientId' => 'YOUR_CLIENT_ID',
  'clientSecret' => 'YOUR_CLIENT_SECRET',
  'redirectUri' => 'YOUR_REDIRECT_URI'
));

$tokenResponse = $acuity->requestAccessToken($_GET['code']);
print_r($tokenResponse);

If everything checks out, we'll respond with JSON and an access_token. If not, we'll do our best to tell you why.

{
  "access_token": "AN_ACCESS_TOKEN",
  "token_type": "Bearer"
}
{
  "error": "invalid_request",
  "message":"The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed. Check the \"code\" parameter."
}

Setting the Authorization header to Bearer AN_ACCESS_TOKEN will authenticate the user's account with our API server.

curl "https://acuityscheduling.com/api/v1/me" \
	-H "Authorization: Bearer AN_ACCESS_TOKEN"
var Acuity = require('acuityscheduling');

var acuity = Acuity.oauth({
  accessToken: 'AN_ACCESS_TOKEN'
});

acuity.request('me', function (err, res, me) {
  if (err) return console.error(err);
  console.log(me);
});
<?php
require_once('vendor/autoload.php');

$acuity = new AcuitySchedulingOAuth(array(
  'accessToken' => 'AN_ACCESS_TOKEN'
));

$me = $acuity->request('me');
print_r($me);

If you're done using a token, you can disable it using our disconnect endpoint:

curl https://acuityscheduling.com/oauth2/disconnect \
 -d access_token=AN_ACCESS_TOKEN \
 -d client_id=YOUR_CLIENT_ID \
 -d client_secret=YOUR_CLIENT_SECRET

About OAuth 2.0

You can learn more about OAuth 2.0 at the helpful community website. Or put on your reading specs and check out the official specification.