Authentication

Overview

Authentication is the process of verifying the identity of a user or application. The iiniit API supports multiple authentication methods, including OAuth2, API keys, and JWT tokens.

OAuth2 Authentication Flow

OAuth2 is the recommended authentication method for applications that need to access user data. It provides a secure way for users to grant limited access to their resources without sharing their credentials.

OAuth2 Flow Diagram

Authorization Code Flow

The Authorization Code flow is the most common OAuth2 flow for web applications. It involves the following steps:

Authorization Request: Your application redirects the user to the iiniit authorization endpoint.

GET https://www.iiniit.com/auth/login?
  response_type=code&
  client_id=YOUR_CLIENT_ID&
  redirect_uri=YOUR_REDIRECT_URI&
  scope=read:user&
  state=RANDOM_STATE_VALUE

User Authorization: The user logs in to iiniit and approves the requested permissions.
Authorization Code: iiniit redirects back to your application with an authorization code.
```
https://your-app.com/callback?code=AUTHORIZATION_CODE&state=RANDOM_STATE_VALUE
```

Token Request: Your application exchanges the authorization code for an access token.

curl --location --request POST '/oauth2/authorize' \
--header 'Content-Type: application/json' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'code=AUTHORIZATION_CODE' \
--data-urlencode 'redirect_uri=YOUR_REDIRECT_URI' \
--data-urlencode 'client_id=YOUR_CLIENT_ID' \
--data-urlencode 'client_secret=YOUR_CLIENT_SECRET'

Access Token Response: iiniit returns an access token and refresh token.

Property	Type	Description
`access_token`	string	The access token to use for API requests
`token_type`	string	The type of token, usually "Bearer"
`expires_in`	number	The number of seconds until the access token expires
`refresh_token`	string	A token that can be used to obtain a new access token when the current one expires
`scope`	string	A space-separated list of scopes that were granted

{
  "access_token": "ACCESS_TOKEN",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "REFRESH_TOKEN",
  "scope": "read:user read:projects"
}

Code Examples

OAuth2 Authentication (JavaScript)

// Step 1: Redirect user to authorization URL
function redirectToAuth() {
  const authUrl = new URL('https://api.iiniit.com/oauth2/authorize');
  authUrl.searchParams.append('response_type', 'code');
  authUrl.searchParams.append('client_id', 'YOUR_CLIENT_ID');
  authUrl.searchParams.append('redirect_uri', 'YOUR_REDIRECT_URI');
  authUrl.searchParams.append('scope', 'read:user read:projects');
  authUrl.searchParams.append('state', generateRandomState());
  
  window.location.href = authUrl.toString();
}

// Step 2: Exchange code for token
async function exchangeCodeForToken(code) {
  const response = await fetch('https://api.iiniit.com/oauth2/token', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
    },
    body: new URLSearchParams({
      grant_type: 'authorization_code',
      code: code,
      redirect_uri: 'YOUR_REDIRECT_URI',
      client_id: 'YOUR_CLIENT_ID',
      client_secret: 'YOUR_CLIENT_SECRET',
    }),
  });
  
  return await response.json();
}

Error Handling

If an error occurs during the authentication process, the authorization server will return an error response. Common errors include:

invalid_request: The request is missing a required parameter or is otherwise malformed
unauthorized_client: The client is not authorized to use this grant type
access_denied: The resource owner denied the request
invalid_scope: The requested scope is invalid, unknown, or malformed
server_error: The authorization server encountered an unexpected error

Next Steps

Now that you understand how to authenticate with the iiniit API, you can: