Authefy SDK

An Authefy software development kit for javascript. Simplifies the use of Authefy endpoints by providing set of libraries that are familiar for javascript developers. It also supports cross-runtime client service that can run on browser and Node.js server without code change.

Build

npm run build transpiles the *.ts from src to build and updates dist files

Installation

To use with node:

$ npm install package;

Then import sdk:

import * as authefy from package;

We are currently supporting esm and umd. To use it directly in the browser:

download the desired module from here. e.g.

wget https://github.com/HighOutputVentures/insignia-sdk/blob/master/dist/umd/index.min.js

Then import the library from browser:

// umd
<script src="./umd/index.min.js"></script>;

// esm
<script type="module">
    import * as authefy from "./esm/index.js" 
</script>

or use jsdelivr links:

<script src="//cdn.jsdelivr.net/gh/HighOutputVentures/insignia-sdk/dist/umd/index.js"></script>

<script src="//cdn.jsdelivr.net/gh/HighOutputVentures/insignia-sdk/dist/umd/index.min.js"></script>

Documentation

Class: WebClient

Handles functions for client's frontend side. Can be run in both browser and nodejs runtime.

• Constructor: WebClient(opts)

  • opt <Object>
    • appId <string> application id

  import { WebClient } from package
  const authefyWebClient = new WebClient({ appId: 'app123' });

• Getter: user

  • Method: create(input)

    • input <Object>

      • username <string> (required)
      • password <string> (required)
      • externalId <string> user reference under application
      • groups <string[]> groups id in array
      • details <Object> user additional information

    • Returns:<Promise> Fufills with <User> upon success.

      await authefyWebClient.user.create({ username: 'john', password: 'doe' })
      // [Object] User 

• Getter: token

  • Method: authenticate(input) For grantType 'bitclout', a new bitclout window will open for the user credentials

    • input <Object>

      • oneOf <Object> (required)
        • grantType <'bitclout'>
        • grantType <'password'>
          • username <string>
          • password <string>
        • grantType <'refreshToken'>
          • refreshToken <string>

    • Returns: <Promise> Fufills with { accessToken: string; refreshToken?: string; expiresIn: number; } upon success.

      await authefyWebClient.token.authenticate({ 
        grantType: 'bitclout'
      })
      await authefyWebClient.token.authenticate({ 
        grantType: 'password', 
        username: 'john', 
        password: 'doe' 
      })
      await authefyWebClient.token.authenticate({ 
        grantType: 'refreshToken', 
        refreshToken: 'eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE2MjEyNTYxNDMsImV4cCI6MTYyMTI1NjIwM30.uc8aXYsWsHZsF-62vKgIEqq8jw_K2bkhIgxB6FadUG-C_Lcl5F-66rRotSWm4_lsaStQ1pJjeRAUMvDh3ikz4g'
      })
      // { accessToken: 'eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE2MjEyNTYxNDMsImV4cCI6MTYyMTI1NjIwM30.uc8aXYsWsHZsF-62vKgIEqq8jw_K2bkhIgxB6FadUG-C_Lcl5F-66rRotSWm4_lsaStQ1pJjeRAUMvDh3ikz4g', refreshToken: 'eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE2MjEyNTYxNDMsImV4cCI6MTYyMTI1NjIwM30.uc8aXYsWsHZsF-62vKgIEqq8jw_K2bkhIgxB6FadUG-C_Lcl5F-66rRotSWm4_lsaStQ1pJjeRAUMvDh3ikz4g', expiresIn: 60000 }

  • Method: revoke(input)

    • input <Object>

      • refreshToken <string> (required)

    • Returns: <Promise> Fufills with boolean upon success.

      await authefyWebClient.token.revoke({ 
        refreshToken: 'eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE2MjEyNTYxNDMsImV4cCI6MTYyMTI1NjIwM30.uc8aXYsWsHZsF-62vKgIEqq8jw_K2bkhIgxB6FadUG-C_Lcl5F-66rRotSWm4_lsaStQ1pJjeRAUMvDh3ikz4g'
      })
      // true

Class: ServerClient

Works only in NodeJS runtime. Handles functions for client's server side.

• Constructor: WebClient(opts)

  • opt <Object>
    • appId <string> application id (required)
    • appKey <string> appliction secret key (required)
    • host <string> Authefy API url. api

  import { ServerClient } from <package>
  const authefyServerClient = new ServerClient({ 
    appId: 'app123', appKey: 'shh' 
  });

• Getter: user

  • Method: create(input)

    • input <Object>

      • username <string> (required)
      • password <string> (required)
      • externalId <string> user reference under application
      • groups <string[]> groups id in array
      • details <Object> user additional information

    • Returns:<Promise> Fufills with <User> upon success.

      await authefyServerClient.user.create({ 
        username: 'john', password: 'doe' 
      })
      // [Object] User 

  • Method: update(id, input)

    • id <string> user id to update

    • input <Object>

      • password <string>
      • isVerified <boolean>
      • groups <string[]>
      • details <Object> user reference under application

    • Returns:<Promise> Fufills with boolean upon success.

      await authefyServerClient.user.update(
        'user123', 
        { 
          details: { name: 'johndoe' }
        }
      )
      // true

  • Method: delete(id)

    • id <string> user id to delete

    • Returns:<Promise> Fufills with boolean upon success.

      await authefyServerClient.user.delete('user123')
      // true

  • Method: read(id)

    • id <string> user id to query

    • Returns:<Promise> Fufills with upon success.

      await authefyServerClient.user.read('user123')
      // true

• Getter: token

  • Method: authenticate(input)

    • input <Object>

      • oneOf <Object> (required)
        • grantType <'bitclout'>
          • token <string>
          • publicKey <string>
        • grantType <'password'>
          • username <string>
          • password <string>
        • grantType <'refreshToken'>
          • refreshToken <string>

    • Returns: <Promise> Fufills with { accessToken: string; refreshToken?: string; expiresIn: number; } upon success.

      await authefyWebClient.token.authenticate({ 
        grantType: 'bitclout', 
        token: 'eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE2MjEyNTYxNDMsImV4cCI6MTYyMTI1NjIwM30.uc8aXYsWsHZsF-62vKgIEqq8jw_K2bkhIgxB6FadUG-C_Lcl5F-66rRotSWm4_lsaStQ1pJjeRAUMvDh3ikz4g', 
        publicKey: 'pubKey123' 
      })
      await authefyWebClient.token.authenticate({ 
        grantType: 'password', 
        username: 'john', 
        password: 'doe' 
      })
      await authefyWebClient.token.authenticate({ 
        grantType: 'refreshToken', 
        refreshToken: 'eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE2MjEyNTYxNDMsImV4cCI6MTYyMTI1NjIwM30.uc8aXYsWsHZsF-62vKgIEqq8jw_K2bkhIgxB6FadUG-C_Lcl5F-66rRotSWm4_lsaStQ1pJjeRAUMvDh3ikz4g'
      })
      // { accessToken: 'eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE2MjEyNTYxNDMsImV4cCI6MTYyMTI1NjIwM30.uc8aXYsWsHZsF-62vKgIEqq8jw_K2bkhIgxB6FadUG-C_Lcl5F-66rRotSWm4_lsaStQ1pJjeRAUMvDh3ikz4g', refreshToken: 'eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE2MjEyNTYxNDMsImV4cCI6MTYyMTI1NjIwM30.uc8aXYsWsHZsF-62vKgIEqq8jw_K2bkhIgxB6FadUG-C_Lcl5F-66rRotSWm4_lsaStQ1pJjeRAUMvDh3ikz4g', expiresIn: 60000 }

  • Method: revoke(input)

    • input <Object>

      • refreshToken <string> (required)

    • Returns: <Promise> Fufills with boolean upon success.

      await authefyWebClient.token.revoke({ 
        refreshToken: 'eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE2MjEyNTYxNDMsImV4cCI6MTYyMTI1NjIwM30.uc8aXYsWsHZsF-62vKgIEqq8jw_K2bkhIgxB6FadUG-C_Lcl5F-66rRotSWm4_lsaStQ1pJjeRAUMvDh3ikz4g'
      })
      // true

  • Method: authorizeBearer(authorization)

    • authorization <string&gt authorization token starts with Bearer;

    • Returns: <Promise> Fufills with { id: string; externalId?: string; iat: number; exp: number; sub: string } upon success.

      await authefyWebClient.token.authorizeBearer('Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE2MjEyNTYxNDMsImV4cCI6MTYyMTI1NjIwM30.uc8aXYsWsHZsF-62vKgIEqq8jw_K2bkhIgxB6FadUG-C_Lcl5F-66rRotSWm4_lsaStQ1pJjeRAUMvDh3ikz4g')
      // { id: '', externalId: '', iat: 1621401772134, exp: 1621401772134,  sub: '' }

• Getter: event

  • Method: listen(options)

    • options <Object>

      • startFromLastEventCursor <string | false | null>
      • type <'UserCreated' | 'UserUpdated' | 'UserDeleted'>
      • reconnect <boolean>

    • Returns: <Promise> Fufills with <EventEmitter> upon success.

    • emitter.on('data', callback)

    • emitter.on('UserCreated' | 'UserUpdated' | 'UserDeleted', callback)

      const emitter = await authefyWebClient.event.listen({ 
        startFromLastEventCursor: false,
        type: 'UserCreated'
        reconnect: false,
      })
      emitter.on('data', event => /* process event */) 
      // or
      emitter.on('UserCreated', event => /* process event */)
      emitter.on('UserUpdated', event => /* process event */)
      emitter.on('UserDeleted', event => /* process event */)

  • Method: fetch(params)

    • params <Object>

      • filter <Object>
        • type: <'UserCreated' | 'UserUpdated' | 'UserDeleted'>
      • sort <ASC | DESC>
      • size <number>
      • after <string>
      • before <string>

    • Returns: <Promise> Fufills with { edges: { UserEvent, cursor: string }[], endCursor?: string, totalCount: number } upon success.

      await authefyWebClient.token.fetch({})

Object: User

• id <string>
• externalId <string>
• username <string>
• password <string>
• groups <string[]>
• details <Object>
• isEmailVerified <boolean>
• isVerified <boolean>

Object: UserEvent

• id <string>
• user <string>
• externalId <string>
• application <string>
• dateTimeCreated <Date>
• cursor <string>
• type <'UserCreated' | 'UserUpdated' | 'UserDeleted'>
• body <Object>