Docs‎ > ‎API Creator‎ > ‎Security‎ > ‎Authentication‎ > ‎Authentication Providers‎ > ‎

Define a Custom Authentication Provider using JavaScript

A custom authentication provider is a piece of JavaScript code, which must follow certain conventions. You must load this piece of code as a JavaScript library in your project.

You then register your authentication provider by creating a new authentication provider in Live API Creator. Select "JavaScript Auth Provider" as the Authentication Method and then enter the "Name for Create Function". This should be the name of your authentication provider function (myAuthProvider in the sample below).

For more information about creating new authentication providers, see Authentication Providers.


An authentication provider is a JavaScript function, which must return an object containing the following functions, each with a specific name and behavior:
  • getConfigInfo
  • configure
  • getLoginInfo
  • authenticate

The general structure is:
function myAuthProvider() {
    return {
        getConfigInfo: function() {...},
        configure: function(values) {...},
        getLoginInfo: function() {...},
        authenticate: function(payload) {...}

The getConfigInfo Function

API Server calls the getConfigInfo function when it instantiates your authentication provider. API Server must return a description of the parameters needed for configuration, as well as the current value for these parameters.

The format for this object is:
return {
    fields: [
            name: "param1",
            display: "Parameter 1",               // The caption for the field in the API Creator
            description: "Blah blah",             // Optional: a short description of this parameter
            length: 40,                           // Optional: maximum length for the value of this parameter
            helpURL: ""  // Optional: a URL to a page describing this parameter
            name: "param2",
            display: "Parameter 2",
            length: 40,
            helpURL: ""
    current: {  // The current (or default) values for the parameters
        param1: valueOfParam1,
        param2: valueOfParam2

Given this, the authentication provider will look like this in the API Creator:

The configure Function

API Creator calls the configure function when the user enters a value for the parameters specified by getConfigInfo and clicks Save.
configure: function(values) {
    param1value = values.param1;
    param2value = values.param2;

The getLoginInfo Function

API Server calls the getLoginInfo function when a client needs to know what kind of information is required for authentication. This describes what the login dialog should look like (assuming the client is an interactive application).

getLoginInfo: function() {
    return {
      fields: [  // Here we only have one field, but it's common to have e.g. username and password
name: 'password',
display: 'Your password',
description: 'Enter your password. This is case-sensitive.',
type: 'text',
length: 30

// You can optionally include up to two links here, which might describe how
// to reset a password, or how to obtain a login.
links: [
display: 'Forgot Password?',
href : ''

The authenticate Function

API Server calls the authenticate function when a client is attempting to authenticate. This is the crux of the authentication provider. There is no constraint on exactly how the user is authenticated.

The argument passed in contains whatever values were provided to the @authentication service. If the caller is well-behaved, the argument should correspond to the parameters described by getLoginInfo, but you should not depend on that.

The authenticate function must return an object containing just an error message if the authentication failed. If the authentication succeeded, then it must return an object with the following properties:

authenticate: function(payload) {

    // Authenticate user here. Could be using LDAP, a database, a web service, etc...
    // If the client is well-behaved, payload should have the properties described by getLoginInfo
    // This code has access to all the libraries selected for the project.

    if ( ... authentication failed ... )
        return {
            errorMessage: "Authentication failed etc..."

    return {
        errorMessage: null,   // Indicates success
        roleNames: ['role1', 'role2'],    // This cannot be empty, otherwise the user will have no permissions
        userData: { employeeId: "12345", region: "US-West"}, // Optional: these properties will be attached to the API key
        userInfo: { email: "" },  // Optional: these properties will be returned along with the API key
        keyLifetimeSeconds: 3600,  // How long the API should be valid for, 0 for perpetual
        lastLogin: new Date(2013, 11, 31), // Optional: last time user logged in (caution: JS Date has 0-based month)
        lastLoginIP: ""   // Optional : the IP from which the user last logged in

Debug your Authentication Provider

Debugging server-side code can be difficult. You can debug your authentication provider using API Creator's simple environment. For details, see the Hello World example.

Authentication Samples

See the Business to Business ExampleAPI Creator publishes several authentication provider services. You can find them on our GitHub account. These samples include Stormpath, Microsoft Azure Active Directory (Azure AD), SQL Server database, LDAP call to third party JDBC driver.

For more information, see Authentication.