Documentation

Everything you need to get started with AuthnzNet

Getting Started

CLI Reference

OAuth Flows

API Reference

Getting Started

Prerequisites

Before you begin, make sure you have the following installed:

.NET 9.0 SDK or later
A code editor (Visual Studio, VS Code, or Rider)
Basic understanding of OAuth 2.0 concepts

Installation

Install the AuthnzNet CLI tool using the dotnet tool command:

dotnet tool install -g AuthnzNet.Cli

First Steps

Start the OAuth server on your local machine:

authnznet server start

The server will start on http://localhost:5000 by default.

Create a tenant to represent your application:

authnznet tenant create --name MyApp --domain myapp.local

Create an OAuth client for your application:

authnznet client create --tenant MyApp --name WebApp \
  --redirect-uri http://localhost:3000/callback \
  --grant-types authorization_code,refresh_token

Save the client_id and client_secret that are displayed. You'll need these for your application.

Add test users to your tenant:

authnznet user create --tenant MyApp \
  --email test@example.com \
  --password Password123! \
  --email-confirmed

Now you can integrate AuthnzNet with your application. Use these endpoints:

Authorization: http://localhost:5000/oauth/authorize
Token: http://localhost:5000/oauth/token
UserInfo: http://localhost:5000/oauth/userinfo

CLI Reference

Server Commands

Start Server

authnznet server start [--port 5000] [--database path/to/db]

Starts the AuthnzNet OAuth server.

Stop Server

authnznet server stop

Stops the running AuthnzNet server.

Tenant Commands

Create Tenant

authnznet tenant create --name <name> --domain <domain>

Creates a new tenant.

List Tenants

authnznet tenant list

Lists all tenants.

Delete Tenant

authnznet tenant delete --name <name>

Deletes a tenant and all associated data.

Client Commands

Create Client

authnznet client create --tenant <tenant> --name <name> \
  --redirect-uri <uri> --grant-types <types>

Creates a new OAuth client. Grant types: authorization_code, client_credentials, password, refresh_token.

List Clients

authnznet client list --tenant <tenant>

Lists all clients for a tenant.

Delete Client

authnznet client delete --tenant <tenant> --client-id <id>

Deletes a client.

User Commands

Create User

authnznet user create --tenant <tenant> --email <email> \
  --password <password> [--email-confirmed]

Creates a new user. Use --email-confirmed to skip email verification.

List Users

authnznet user list --tenant <tenant>

Lists all users for a tenant.

Delete User

authnznet user delete --tenant <tenant> --email <email>

Deletes a user.

OAuth 2.0 Flows

The Authorization Code flow is the most secure OAuth 2.0 flow, recommended for web applications with a server-side component.

Step 1: Authorization Request

Redirect the user to:

GET http://localhost:5000/oauth/authorize?
  response_type=code&
  client_id=YOUR_CLIENT_ID&
  redirect_uri=YOUR_REDIRECT_URI&
  scope=openid profile email&
  state=RANDOM_STATE

Step 2: Exchange Code for Token

After user authorization, exchange the code:

POST http://localhost:5000/oauth/token
Content-Type: application/x-www-form-urlencoded

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

Step 3: Use Access Token

GET http://localhost:5000/oauth/userinfo
Authorization: Bearer ACCESS_TOKEN

Use this flow for machine-to-machine authentication where there is no user involved.

Request Access Token

POST http://localhost:5000/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET&
scope=api

The client credentials flow does not involve a user, so it cannot be used to access user-specific data.

Use this flow when you trust the client application with user credentials. Not recommended for production use.

Request Access Token

POST http://localhost:5000/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=password&
username=USER_EMAIL&
password=USER_PASSWORD&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET

This flow is only suitable for first-party applications you fully control. Use Authorization Code flow whenever possible.

Use refresh tokens to obtain new access tokens without requiring the user to re-authenticate.

Refresh Access Token

POST http://localhost:5000/oauth/token
Content-Type: application/x-www-form-urlencoded

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

API Reference

Authorization Endpoint

GET /oauth/authorize

Initiates the OAuth authorization flow.

Parameters:

response_type - Must be "code" for authorization code flow
client_id - Your OAuth client ID
redirect_uri - Where to redirect after authorization
scope - Space-separated list of scopes (e.g., "openid profile email")
state - Random string to prevent CSRF attacks

Token Endpoint

POST /oauth/token

Exchanges authorization codes for access tokens or refreshes tokens.

Parameters:

grant_type - authorization_code, client_credentials, password, or refresh_token
client_id - Your OAuth client ID
client_secret - Your OAuth client secret
Additional parameters based on grant_type

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "def50200...",
  "scope": "openid profile email"
}

UserInfo Endpoint

GET /oauth/userinfo

Returns information about the authenticated user.

Headers:

Authorization: Bearer ACCESS_TOKEN

Response:

{
  "sub": "user-id",
  "email": "user@example.com",
  "email_verified": true,
  "name": "John Doe",
  "given_name": "John",
  "family_name": "Doe"
}

Token Revocation Endpoint

POST /oauth/revoke

Revokes an access or refresh token.

Parameters:

token - The token to revoke
token_type_hint - Optional: "access_token" or "refresh_token"