Authnest Developer Documentation

Getting Started

Welcome to Authnest, a powerful authentication solution for your B2B applications. Follow these steps to integrate Authnest into your project:

Sign up for an Authnest developer account
Visit the Authnest Developer page and create your developer account using your email address.
Create a new app in the Authnest dashboard
Once logged in, navigate to the dashboard and click on "Create New App". Provide a name for your app and basic information such as contact email, homepage URL, privacy policy URL, and terms of service URL.
Configure your app settings and OAuth 2.0 clients
In your app settings, you can configure:
- Allowed domains and emails
- Blocked domains and emails
- Email provider restrictions
- OAuth scopes
- Custom profile fields
Create an OAuth 2.0 client for your app by specifying the client name, authorized JavaScript origins, and redirect URIs.
Integrate Authnest into your application
Use the Authnest REST API to implement authentication in your application. See the API Reference section for more details.

Add the "Continue with Authnest" button

Include the Authnest login button in your application:

<a href="https://authnest.com/oauth2/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&scope=openid%20email%20profile%20offline">
  <img src="https://authnest.com/authnest-logo.png" alt="Continue with Authnest" />
  Continue with Authnest
</a>

Note: Replace YOUR_CLIENT_ID and YOUR_REDIRECT_URI with your actual client ID and redirect URI.

Authentication Flow

Authnest uses the OAuth 2.0 protocol for authentication. Here's a detailed overview of the authentication flow:

Redirect the user to the Authnest authorization endpoint
Construct the authorization URL with your client ID, redirect URI, requested scopes, and optional parameters:
```
https://authnest.com/oauth2/authorize?
  response_type=code&
  client_id=YOUR_CLIENT_ID&
  redirect_uri=YOUR_REDIRECT_URI&
  scope=openid%20email%20profile%20offline&
  state=RANDOM_STATE_VALUE
          
```
Note: The state parameter is optional but recommended for security purposes. It helps prevent cross-site request forgery (CSRF) attacks.
User selects their work email to authorize
The user is presented with Authnest's login page, where they can select their work email to authorize access.
Authnest redirects back to your app
After successful authentication, Authnest redirects the user back to your specified redirect URI with an authorization code:
```
YOUR_REDIRECT_URI?code=AUTHORIZATION_CODE&state=RANDOM_STATE_VALUE
          
```

Exchange the authorization code for tokens

Make a POST request to the token endpoint to exchange the authorization code for access and ID tokens:

POST /oauth2/token HTTP/1.1
Host: api.authnest.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET&
code=AUTHORIZATION_CODE&
redirect_uri=YOUR_REDIRECT_URI

Use the userinfo endpoint and decode the ID token

You can retrieve user information in two ways:

Call the userinfo endpoint using the access token:

        GET /oauth2/userinfo HTTP/1.1
        Host: api.authnest.com
        Authorization: Bearer ACCESS_TOKEN

Decode and verify the JWT ID token:

        // Example using a JWT library (implementation may vary)
        const decodedToken = jwt.verify(idToken, publicKey, { algorithms: ['RS256'] });
        console.log(decodedToken);

The decoded ID token contains claims about the authenticated user.

Note: To obtain the public key for token verification, refer to the Public Key Retrieval section below.

Public Key Retrieval

To verify the JWT ID token, you need to get the public key:

Fetch the JWKS (JSON Web Key Set) from the well-known endpoint:

    GET /.well-known/jwks.json HTTP/1.1
    Host: api.authnest.com

Extract the public key from the JWKS response:

    // Example using a JWT library (implementation may vary)
    const jwks = await fetchJwks('https://api.authnest.com/.well-known/jwks.json');
    const key = jwks.keys.find(k => k.kid === decodedToken.header.kid);
    const publicKey = await jose.importJWK(key, key.alg);
    
    // Verify the ID token
    const { payload } = await jose.jwtVerify(idToken, publicKey);
    console.log(payload);

API Reference

OAuth 2.0 Endpoints

Authorization endpoint: https://authnest.com/oauth2/authorize
Token endpoint: https://api.authnest.com/oauth2/token
User info endpoint: https://api.authnest.com/oauth2/userinfo
Token info endpoint: https://api.authnest.com/oauth2/tokeninfo
Token revocation endpoint: https://api.authnest.com/oauth2/revoke

Token Endpoint

Use this endpoint to exchange an authorization code for access and ID tokens, or to refresh an access token.

POST /oauth2/token HTTP/1.1
Host: api.authnest.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET&
code=AUTHORIZATION_CODE&
redirect_uri=YOUR_REDIRECT_URI

For refreshing a token:

POST /oauth2/token HTTP/1.1
Host: api.authnest.com
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET&
refresh_token=REFRESH_TOKEN

Response:

{
  "access_token": "ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": 3600,
  "id_token": "ID_TOKEN",
  "refresh_token": "REFRESH_TOKEN"
}

User Info Endpoint

Retrieve information about the authenticated user using this endpoint.

GET /oauth2/userinfo HTTP/1.1
Host: api.authnest.com
Authorization: Bearer ACCESS_TOKEN

Response:

{
  "sub": "user_12345",
  "email": "[email protected]",
  "email_verified": true,
  "name": "John Doe",
  "given_name": "John",
  "family_name": "Doe",
  "picture": "https://example.com/photo.jpg",
  "locale": "en-US"
}

Token Info Endpoint

Get information about an access token or ID token.

GET /oauth2/tokeninfo?access_token=ACCESS_TOKEN HTTP/1.1
Host: api.authnest.com

Response:

{
  "iss": "https://authnest.com",
  "sub": "user_12345",
  "aud": "YOUR_CLIENT_ID",
  "exp": 1619876543,
  "iat": 1619872943,
  "scope": "openid email profile offline"
}

Token Revocation Endpoint

Use this endpoint to revoke an access token or refresh token.

POST /oauth2/revoke HTTP/1.1
Host: api.authnest.com
Content-Type: application/x-www-form-urlencoded

token=TOKEN_TO_REVOKE&
token_type_hint=access_token&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET

Parameters:

token: The token to be revoked.
token_type_hint: Optional. Either 'access_token' or 'refresh_token'.
client_id: Your client ID.
client_secret: Your client secret.

Response: HTTP 200 OK (empty response body on success)

Security Best Practices

To ensure the security of your application and user data, follow these best practices:

Use HTTPS: Always use HTTPS for all communication between your app, users, and Authnest.
Secure storage of client secrets: Never expose your client secret in client-side code. Use it only in server-side applications.
Validate tokens: Always validate access tokens and ID tokens before trusting the information they contain.
Short-lived access tokens: Use short-lived access tokens and refresh tokens for long-lived sessions.
Secure your redirect URIs: Ensure that your redirect URIs are properly secured and can't be manipulated by attackers.

Support and Community

If you need help or want to connect with other developers using Authnest, you can:

Discord server for real-time chat
Contact our support team at [email protected]