Skip to content

OAuth API

The OAuth API is an extension of the Users API and provides methods to manage OAuth information for a client-side created user.

Linking an OAuth provider allows you to log in a user with either a username and password, or OAuth credentials.

The main use cases for the OAuth API are Facebook Login, Google Sign-In, and Devices as Users.

addAuthProvider

Link OAuth provider information to a user.

core.users.addAuthProvider(auth_tbl, listener)

Parameters

Name Description Type Required
auth_tbl The auth table for the call (see below). Table Y
listener The api listener callback function. Function Y

Auth Table Keys

Name Description Type Required
user_id The users unique identifier. String Y
provider The OAuth provider constant (see OAuth Constants). Const Y
auth Table of the provider information in key/value format (see below). Table Y

Auth Table Keys

Name Description Type Required
client_id The immutable ID provided by the OAuth provider. String Y
access_token OAuth provider access token, if any. String N
access_token_expiry The lifetime of the access token as a UNIX timestamp, if any. Number N

Event Response

On success, the result will hold the added provider information as a table.

The returned table contains the following keys:

  • client_id (string)
  • access_token (string)
  • access_token_expiry (number)
  • access_token_expired (boolean)
  • provider (string)

Example

local function apiResponse( evt )
  if evt.error then
    print(evt.error)
  else
    local oauth_info = evt.result 
  end
end

core.users.addAuthProvider({
  user_id = "aad3eba3...",
  provider = core.FACEBOOK,
  auth = {
    client_id = "fb-id-1234",
    access_token = "1234abcd",
    access_token_expiry = 1516647155
  }
}, apiResponse)

getAuthProvider

Get OAuth provider information for a user.

core.users.getAuthProvider(auth_tbl, listener)

Parameters

Name Description Type Required
auth_tbl The auth table for the call (see below). Table Y
listener The api listener callback function. Function Y

Auth Table Keys

Name Description Type Required
user_id The users unique identifier. String Y
provider The OAuth provider constant (see OAuth Constants). Const Y

Event Response

On success, the result will hold the provider information as a table.

The returned table contains the following keys

  • client_id (string)
  • access_token (string)
  • access_token_expiry (number)
  • access_token_expired (boolean)
  • provider (string)

Example

local function apiResponse( evt )
  if evt.error then
    print(evt.error)
  else
    local oauth_info = evt.result 

    --maybe check for expired token
    if oauth_info.access_token_expired then
      --token expired
    else
      --token valid
    end
  end
end

core.users.getAuthProvider({
  user_id = "aad3eba3...",
  provider = core.FACEBOOK
}, apiResponse)

updateAuthProvider

Update OAuth provider information for a user.

core.users.updateAuthProvider(auth_tbl, listener)

Parameters

Name Description Type Required
auth_tbl The auth table for the call (see below). Table Y
listener The api listener callback function. Function Y

Auth Table Keys

Name Description Type Required
user_id The users unique identifier. String Y
provider The OAuth provider constant (see OAuth Constants). Const Y
update A table of key/value pairs of provider information. Table Y

The following keys are updatable:

  • client_id (string)
  • access_token (string)
  • access_token_expiry (number)

Event Response

On success, the result will hold the updated provider information as a table (see getAuthProvider).

Example

local function apiResponse( evt )
  if evt.error then
    print(evt.error)
  else
    local oauth_info = evt.result 
  end
end

core.users.updateAuthProvider({
  user_id = "aad3eba3...",
  provider = core.FACEBOOK,
  update = {
    access_token = "1234abcd",
    access_token_expiry = 1516647155
  }
}, apiResponse)

removeAuthProvider

Remove an OAuth provider from a user.

core.users.removeAuthProvider(auth_tbl, listener)

Parameters

Name Description Type Required
auth_tbl The auth table for the call (see below). Table Y
listener The api listener callback function. Function Y

Auth Table Keys

Name Description Type Required
user_id The users unique identifier. String Y
provider The OAuth provider constant (see OAuth Constants). Const Y

Event Response

On success, the result will hold the user_id key as a string value.

Example

local function apiResponse( evt )
  if evt.error then
    print(evt.error)
  else
    local user_id = evt.result.user_id 
  end
end

core.users.removeAuthProvider({
  user_id = "aad3eba3...",
  provider = core.FACEBOOK
}, apiResponse)

accessTokenExpired

Conditionally check if a users access token has expired for the specified provider.

core.users.accessTokenExpired(auth_tbl, listener)

Parameters

Name Description Type Required
auth_tbl The auth table for the call (see below). Table Y
listener The api listener callback function. Function Y

Auth Table Keys

Name Description Type Required
user_id The users unique identifier. String Y
provider The OAuth provider constant (see OAuth Constants). Const Y

Event Response

On success, the result will hold the expired key as a boolean value.

Example

local function apiResponse( evt )
  if evt.error then
    print(evt.error)
  else
    if evt.result.expired then
      --token is expired
    else
      --token is valid
    end
  end
end

core.users.accessTokenExpired({
  user_id = "aad3eba3...",
  provider = core.FACEBOOK
}, apiResponse)

updateTokenExpiry

Update the provider token expiration time. This is a convenience method, see also updateAuthProvider.

core.users.updateTokenExpiry(auth_tbl, listener)

Parameters

Name Description Type Required
auth_tbl The auth table for the call (see below). Table Y
listener The api listener callback function. Function Y

Auth Table Keys

Name Description Type Required
user_id The users unique identifier. String Y
provider The OAuth provider constant (see OAuth Constants). Const Y
expiry The new access token expiration time as a UNIX timestamp. Number Y
token Optionally update the access token string as well. String N

Event Response

On success, the result will hold the updated provider information as a table (see getAuthProvider).

Example

local function apiResponse( evt )
  if evt.error then
    print(evt.error)
  else
    local oauth_info = evt.result 
  end
end

core.users.updateTokenExpiry({
  user_id = "aad3eba3...",
  provider = core.FACEBOOK,
  expiry = 1516647155
}, apiResponse)

OAuth Constants

Used for the provider parameter in OAuth methods.

Constant Description See Also
core.FACEBOOK Marks a provider as Facebook. Facebook Login
core.GOOGLE Marks a provider as Google. Google Sign-In
core.OPENUDID Marks a provider as OpenUDID Devices As Users