# Okta Developer Documentation

Okta is a cloud-based identity and access management (IAM) platform that provides authentication, authorization, and user management services for applications. The Okta platform enables developers to securely authenticate users using OAuth 2.0 and OpenID Connect (OIDC) protocols, manage user lifecycles through SCIM provisioning, and extend functionality through webhooks (event hooks and inline hooks). Okta supports multiple integration patterns including redirect-based authentication, embedded Sign-In Widget, and direct API access for server-side applications.

The Okta APIs and SDKs allow developers to implement single sign-on (SSO) across web, mobile, and native applications. Key capabilities include user authentication flows (Authorization Code, Authorization Code with PKCE, Client Credentials), token management (access tokens, refresh tokens, ID tokens), multi-factor authentication (MFA), and real-time event notifications. Okta provides official SDKs for JavaScript, React, Angular, Vue, Node.js, Java Spring Boot, .NET Core, Python, Go, iOS, and Android platforms.

---

## OAuth 2.0 Authorization Code Flow

The Authorization Code flow is the recommended OAuth 2.0 flow for server-side web applications that can securely store client secrets. The flow involves redirecting users to Okta for authentication and exchanging an authorization code for access and ID tokens.

```bash
# Step 1: Request authorization code - redirect user to this URL
https://{yourOktaDomain}/oauth2/v1/authorize?
   client_id=0oabucvyc38HLL1ef0h7&
   response_type=code&
   scope=openid%20profile%20email&
   redirect_uri=https%3A%2F%2Fexample.com%2Fcallback&
   state=state-296bc9a0-a2a2-4a57-be1a-d0e2fd9bb601

# After user authenticates, Okta redirects to:
# https://example.com/callback?code=P5I7mdxxdv13_JfXrCSq&state=state-296bc9a0-a2a2-4a57-be1a-d0e2fd9bb601

# Step 2: Exchange authorization code for tokens
curl --request POST \
  --url https://{yourOktaDomain}/oauth2/v1/token \
  --header 'accept: application/json' \
  --header 'authorization: Basic MG9hY...' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'grant_type=authorization_code&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback&code=P5I7mdxxdv13_JfXrCSq'

# Response:
# {
#     "access_token": "eyJhbG[...]9pDQ",
#     "token_type": "Bearer",
#     "expires_in": 3600,
#     "scope": "openid profile email",
#     "id_token": "eyJhbG[...]RTM0A"
# }
```

---

## OAuth 2.0 Authorization Code Flow with PKCE

The Authorization Code flow with Proof Key for Code Exchange (PKCE) is the recommended flow for single-page applications (SPAs), mobile apps, and native applications where client secrets cannot be securely stored. PKCE prevents authorization code interception attacks by using a code verifier and code challenge.

```bash
# Step 1: Generate PKCE code verifier and challenge
# Code verifier: Random URL-safe string with minimum length of 43 characters
# Code challenge: Base64-encoded SHA-256 hash of the code verifier

# Example PKCE values:
# {
#   "code_verifier":"M25iVXpKU3puUjFaYWg3T1NDTDQtcW1ROUY5YXlwalNoc0hhakxifmZHag",
#   "code_challenge":"qjrzSW9gMiUgpUvqgEPE4_-8swvyCtfOVvg55o5S_es"
# }

# Step 2: Request authorization code with code challenge
https://{yourOktaDomain}/oauth2/v1/authorize?
   client_id=0oabygpxgk9lXaMgF0h7&
   response_type=code&
   scope=openid%20profile&
   redirect_uri=yourApp%3A%2Fcallback&
   state=state-8600b31f-52d1-4dca-987c-386e3d8967e9&
   code_challenge_method=S256&
   code_challenge=qjrzSW9gMiUgpUvqgEPE4_-8swvyCtfOVvg55o5S_es

# Step 3: Exchange code for tokens using code verifier (no client secret required)
curl --request POST \
  --url https://{yourOktaDomain}/oauth2/v1/token \
  --header 'accept: application/json' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'grant_type=authorization_code&client_id=0oabygpxgk9lXaMgF0h7&redirect_uri=yourApp%3A%2Fcallback&code=CKA9Utz2GkWlsrmnqehz&code_verifier=M25iVXpKU3puUjFaYWg3T1NDTDQtcW1ROUY5YXlwalNoc0hhakxifmZHag'

# Response:
# {
#     "access_token": "eyJhb[...]Hozw",
#     "expires_in": 3600,
#     "id_token": "eyJhb[...]jvCw",
#     "scope": "openid profile",
#     "token_type": "Bearer"
# }
```

---

## OAuth 2.0 Client Credentials Flow

The Client Credentials flow is used for machine-to-machine (M2M) communication where there is no end user involved. This flow is appropriate for server-side applications, daemons, and backend services that need to authenticate with their own credentials.

```bash
# Base64-encode client credentials: echo -n 'clientId:clientSecret' | base64

# Request access token using client credentials
curl --request POST \
  --url https://{yourOktaDomain}/oauth2/default/v1/token \
  --header 'accept: application/json' \
  --header 'authorization: Basic MG9hY...' \
  --header 'cache-control: no-cache' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'grant_type=client_credentials&scope=customScope'

# Response:
# {
#     "access_token": "eyJhbG[...]1LQ",
#     "token_type": "Bearer",
#     "expires_in": 3600,
#     "scope": "customScope"
# }
```

---

## Refresh Access Tokens

Refresh tokens allow applications to obtain new access tokens without requiring the user to re-authenticate. Include the `offline_access` scope in your initial authorization request to receive a refresh token.

```bash
# Get authorization code with offline_access scope
curl -X GET 'https://{yourOktaDomain}/oauth2/v1/authorize?client_id={clientId}&response_type=code&scope=openid%20offline_access&redirect_uri=yourApp%3A%2Fcallback&state=237c671a-29d7-11eb-adc1-0242ac120002'

# Exchange code for tokens (includes refresh_token)
curl --location --request POST 'https://{yourOktaDomain}/oauth2/v1/token' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic {Base64({clientId}:{clientSecret})}' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=authorization_code' \
  -d 'redirect_uri={redirectUri}' \
  -d 'code=iyz1Lpim4NgN6gDQdT1a9PJDVTaCdxG1wJMYiUkfGts' \
  -d 'scope=openid offline_access'

# Use refresh token to get new access token
curl --form POST https://{yourOktaDomain}/oauth2/v1/token \
  -H 'accept: application/json' \
  -H 'authorization: Basic MG9hYmg3M...' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'grant_type=refresh_token' \
  -d 'redirect_uri=http://localhost:8080' \
  -d 'scope=offline_access%20openid' \
  -d 'refresh_token=MIOf-U1zQbyfa3MUfJHhvnUqIut9ClH0xjlDXGJAyqo'

# Response:
# {
#     "access_token": "eyJhbGciOiJ[...]K1Sun9bA",
#     "token_type": "Bearer",
#     "expires_in": 3600,
#     "scope": "offline_access openid",
#     "refresh_token": "MIOf-U1zQbyfa3MUfJHhvnUqIut9ClH0xjlDXGJAyqo",
#     "id_token": "eyJraWQiO[...]hMEJQX6WRQ"
# }
```

---

## Node.js Express OIDC Integration

Integrate Okta authentication into a Node.js Express application using the passport-openidconnect strategy. This approach handles the OAuth 2.0 flow automatically and manages user sessions.

```javascript
// Install required packages
// npm install express-session passport passport-openidconnect

// app.js - Configure Express with Okta OIDC
const express = require('express');
const session = require('express-session');
const passport = require('passport');
const { Strategy } = require('passport-openidconnect');

const app = express();

// Session configuration
app.use(session({
  secret: 'your-secure-session-secret',
  resave: false,
  saveUninitialized: true
}));

app.use(passport.initialize());
app.use(passport.session());

// Configure Okta OIDC Strategy
passport.use('oidc', new Strategy({
  issuer: 'https://{yourOktaDomain}',
  authorizationURL: 'https://{yourOktaDomain}/oauth2/v1/authorize',
  tokenURL: 'https://{yourOktaDomain}/oauth2/v1/token',
  userInfoURL: 'https://{yourOktaDomain}/oauth2/v1/userinfo',
  clientID: '{clientID}',
  clientSecret: '{clientSecret}',
  callbackURL: 'http://localhost:3000/authorization-code/callback',
  scope: 'openid profile'
}, (issuer, profile, done) => {
  return done(null, profile);
}));

passport.serializeUser((user, next) => {
  next(null, user);
});

passport.deserializeUser((obj, next) => {
  next(null, obj);
});

// Login route - redirects to Okta
app.get('/login', passport.authenticate('oidc'));

// Callback route - handles OAuth response
app.use('/authorization-code/callback',
  passport.authenticate('oidc', { failureMessage: true, failWithError: true }),
  (req, res) => {
    res.redirect('/profile');
  }
);

// Protected profile route
app.get('/profile', (req, res) => {
  if (!req.isAuthenticated()) {
    return res.redirect('/login');
  }
  res.json(req.user);
});

// Logout route
app.post('/signout', (req, res) => {
  req.logout();
  res.redirect('/');
});

app.listen(3000, () => console.log('Server running on http://localhost:3000'));
```

---

## Protect API Endpoints with JWT Verification

Secure your Node.js API endpoints by validating Okta-issued JWT access tokens. The @okta/jwt-verifier package handles token validation including signature verification and claims checking.

```javascript
// Install: npm install @okta/jwt-verifier express

const express = require('express');
const OktaJwtVerifier = require('@okta/jwt-verifier');

const app = express();

// Configure JWT Verifier
const oktaJwtVerifier = new OktaJwtVerifier({
  issuer: 'https://{yourOktaDomain}/oauth2/{yourAuthServerName}'
});
const audience = '{yourAudience}'; // e.g., 'api://default'

// Authentication middleware
const authenticationRequired = async (req, res, next) => {
  const authHeader = req.headers.authorization || '';
  const match = authHeader.match(/Bearer (.+)/);

  if (!match) {
    return res.status(401).send('Authorization header required');
  }

  try {
    const accessToken = match[1];
    if (!accessToken) {
      return res.status(401).send('Not authorized');
    }
    // Verify and decode the JWT
    req.jwt = await oktaJwtVerifier.verifyAccessToken(accessToken, audience);
    next();
  } catch (err) {
    return res.status(401).send(err.message);
  }
};

// Public endpoint
app.get('/api/hello', (req, res) => {
  res.send('Hello world!');
});

// Protected endpoint - requires valid access token
app.get('/api/whoami', authenticationRequired, (req, res) => {
  res.json(req.jwt?.claims);
});

// Protect all routes under /api/secure
app.use('/api/secure', authenticationRequired);

app.get('/api/secure/data', (req, res) => {
  res.json({
    message: 'This is protected data',
    user: req.jwt.claims.sub
  });
});

app.listen(3000, () => console.log('API server running on port 3000'));

// Example curl command to test protected endpoint:
// curl -H "Authorization: Bearer eyJhbG..." http://localhost:3000/api/whoami
```

---

## Okta API Token Authentication

Use Okta API tokens to authenticate requests to Okta Management APIs. API tokens use the SSWS authentication scheme and inherit the privilege level of the admin account that created them.

```bash
# Using API token in Authorization header
curl --request GET \
  --url https://{yourOktaDomain}/api/v1/users \
  --header 'Accept: application/json' \
  --header 'Authorization: SSWS 00QCjAl4MlV-WPXM...0HmjFx-vbGua'

# Create a new user
curl --request POST \
  --url https://{yourOktaDomain}/api/v1/users?activate=true \
  --header 'Accept: application/json' \
  --header 'Authorization: SSWS {api_token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "profile": {
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@example.com",
      "login": "john.doe@example.com"
    },
    "credentials": {
      "password": { "value": "TempPassword123!" }
    }
  }'

# List all applications
curl --request GET \
  --url https://{yourOktaDomain}/api/v1/apps \
  --header 'Accept: application/json' \
  --header 'Authorization: SSWS {api_token}'

# Get System Log events
curl --request GET \
  --url 'https://{yourOktaDomain}/api/v1/logs?filter=eventType eq "user.lifecycle.deactivate"' \
  --header 'Accept: application/json' \
  --header 'Authorization: SSWS {api_token}'
```

---

## Token Introspection Endpoint

Validate access or refresh tokens remotely using the Token Introspection endpoint. This is useful when you need to verify a token hasn't been revoked, though it adds network latency compared to local JWT validation.

```bash
# Introspect an access token
curl --request POST \
  --url https://{yourOktaDomain}/oauth2/default/v1/introspect \
  --header 'Accept: application/json' \
  --header 'Authorization: Basic {Base64(clientId:clientSecret)}' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'token=eyJhbGciOiJSUzI1NiJ9...&token_type_hint=access_token'

# Response for active token:
# {
#     "active": true,
#     "scope": "openid profile",
#     "username": "john.doe@example.com",
#     "exp": 1640000000,
#     "iat": 1639996400,
#     "sub": "john.doe@example.com",
#     "aud": "api://default",
#     "iss": "https://{yourOktaDomain}/oauth2/default",
#     "jti": "AT.xyz123",
#     "token_type": "Bearer",
#     "client_id": "0oabcdefg"
# }

# Response for inactive/revoked token:
# {
#     "active": false
# }
```

---

## Event Hooks Implementation

Event hooks are outbound calls from Okta that notify your external service when events occur in your Okta org. Implement event hooks to sync user data, trigger workflows, or integrate with external systems.

```javascript
// Node.js Express event hook endpoint
const express = require('express');
const app = express();
app.use(express.json());

// One-time verification endpoint (Okta calls this to verify your endpoint)
app.get('/userDeactivated', (req, res) => {
  const returnValue = {
    verification: req.headers['x-okta-verification-challenge']
  };
  console.log('Event hook verification request received.');
  res.json(returnValue);
});

// Event hook handler for user deactivation events
app.post('/userDeactivated', (req, res) => {
  // Extract user information from the event
  const event = req.body.data.events[0];
  const userId = event.target[0].id;
  const userEmail = event.target[0].alternateId;
  const displayName = event.target[0].displayName;

  console.log(`User ${displayName} (${userEmail}) has been deactivated!`);

  // Process the event (e.g., update external systems, send notifications)
  // Your custom logic here...

  // Respond with 200 OK to acknowledge receipt
  res.sendStatus(200);
});

app.listen(3000);

// Event hook payload structure:
// {
//   "eventType": "com.okta.event_hook",
//   "data": {
//     "events": [{
//       "eventType": "user.lifecycle.deactivate",
//       "target": [{
//         "id": "00u3m90rsKgGQ0G6L1d76",
//         "type": "User",
//         "alternateId": "john.doe@example.com",
//         "displayName": "John Doe"
//       }]
//     }]
//   }
// }
```

---

## SCIM 2.0 Provisioning API

SCIM (System for Cross-domain Identity Management) enables automatic user provisioning between Okta and your application. Implement SCIM endpoints to create, update, deactivate, and sync users from Okta to your service.

```bash
# SCIM 2.0 Base URL structure
# https://your-app.example.com/scim/v2

# Required SCIM endpoints:
# GET    /Users                - List users
# GET    /Users/{id}           - Get user by ID
# POST   /Users                - Create user
# PUT    /Users/{id}           - Replace user
# PATCH  /Users/{id}           - Update user attributes
# DELETE /Users/{id}           - Delete user
# GET    /ServiceProviderConfig - SCIM configuration

# Example: Create user request from Okta
# POST /scim/v2/Users
# Content-Type: application/scim+json
# Authorization: Bearer {token}
#
# {
#   "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
#   "userName": "john.doe@example.com",
#   "name": {
#     "givenName": "John",
#     "familyName": "Doe"
#   },
#   "emails": [{
#     "primary": true,
#     "value": "john.doe@example.com",
#     "type": "work"
#   }],
#   "active": true
# }

# Example: Create user response
# HTTP/1.1 201 Created
# Content-Type: application/scim+json
#
# {
#   "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
#   "id": "unique-user-id-12345",
#   "userName": "john.doe@example.com",
#   "name": {
#     "givenName": "John",
#     "familyName": "Doe"
#   },
#   "emails": [{
#     "primary": true,
#     "value": "john.doe@example.com",
#     "type": "work"
#   }],
#   "active": true,
#   "meta": {
#     "resourceType": "User",
#     "created": "2024-01-15T10:30:00Z",
#     "lastModified": "2024-01-15T10:30:00Z"
#   }
# }

# Example: Deactivate user (PATCH)
# PATCH /scim/v2/Users/{id}
# {
#   "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
#   "Operations": [{
#     "op": "replace",
#     "value": { "active": false }
#   }]
# }
```

---

## Sign-In Widget Integration

The Okta Sign-In Widget is a JavaScript library that provides a fully-featured and customizable login experience. It handles authentication flows, MFA enrollment, and password recovery out of the box.

```html
<!DOCTYPE html>
<html>
<head>
  <!-- Include Sign-In Widget CSS -->
  <link href="https://global.oktacdn.com/okta-signin-widget/7.x/css/okta-sign-in.min.css" type="text/css" rel="stylesheet"/>
</head>
<body>
  <div id="widget-container"></div>

  <!-- Include Sign-In Widget JS -->
  <script src="https://global.oktacdn.com/okta-signin-widget/7.x/js/okta-sign-in.min.js" type="text/javascript"></script>

  <script type="text/javascript">
    const signIn = new OktaSignIn({
      baseUrl: 'https://{yourOktaDomain}',
      clientId: '{clientId}',
      redirectUri: 'https://your-app.example.com/callback',
      authParams: {
        issuer: 'https://{yourOktaDomain}/oauth2/default',
        scopes: ['openid', 'profile', 'email'],
        pkce: true
      },
      features: {
        registration: true,           // Enable self-service registration
        rememberMe: true,             // Enable "Remember me" checkbox
        multiOptionalFactorEnroll: true  // Enable MFA enrollment
      }
    });

    // Render the widget
    signIn.showSignInToGetTokens({
      el: '#widget-container'
    }).then(function(tokens) {
      // Handle successful authentication
      console.log('ID Token:', tokens.idToken);
      console.log('Access Token:', tokens.accessToken);

      // Store tokens and redirect user
      signIn.authClient.tokenManager.setTokens(tokens);
      window.location.href = '/dashboard';
    }).catch(function(error) {
      console.error('Authentication error:', error);
    });
  </script>
</body>
</html>
```

---

## React SPA with Okta Auth

Integrate Okta authentication into a React single-page application using the @okta/okta-react SDK. This provides React components and hooks for managing authentication state.

```jsx
// Install: npm install @okta/okta-react @okta/okta-auth-js react-router-dom

// App.jsx
import React from 'react';
import { BrowserRouter as Router, Route, Routes } from 'react-router-dom';
import { Security, LoginCallback, useOktaAuth } from '@okta/okta-react';
import { OktaAuth } from '@okta/okta-auth-js';

const oktaAuth = new OktaAuth({
  issuer: 'https://{yourOktaDomain}/oauth2/default',
  clientId: '{clientId}',
  redirectUri: window.location.origin + '/login/callback',
  scopes: ['openid', 'profile', 'email'],
  pkce: true
});

// Protected component that requires authentication
const Profile = () => {
  const { authState, oktaAuth } = useOktaAuth();

  if (!authState || !authState.isAuthenticated) {
    return <div>Loading...</div>;
  }

  const logout = async () => {
    await oktaAuth.signOut();
  };

  return (
    <div>
      <h1>Welcome, {authState.idToken?.claims.name}!</h1>
      <p>Email: {authState.idToken?.claims.email}</p>
      <button onClick={logout}>Logout</button>
    </div>
  );
};

// Login component
const Login = () => {
  const { oktaAuth } = useOktaAuth();

  const login = async () => {
    await oktaAuth.signInWithRedirect();
  };

  return (
    <div>
      <h1>Please log in</h1>
      <button onClick={login}>Login with Okta</button>
    </div>
  );
};

// Require authentication wrapper
const RequireAuth = ({ children }) => {
  const { authState } = useOktaAuth();

  if (!authState || !authState.isAuthenticated) {
    return <Login />;
  }

  return children;
};

// Main App
const App = () => {
  const restoreOriginalUri = async (_oktaAuth, originalUri) => {
    window.location.replace(originalUri || '/');
  };

  return (
    <Router>
      <Security oktaAuth={oktaAuth} restoreOriginalUri={restoreOriginalUri}>
        <Routes>
          <Route path="/" element={<Home />} />
          <Route path="/login/callback" element={<LoginCallback />} />
          <Route path="/profile" element={
            <RequireAuth>
              <Profile />
            </RequireAuth>
          } />
        </Routes>
      </Security>
    </Router>
  );
};

export default App;
```

---

## Spring Boot Resource Server

Configure a Spring Boot application as an OAuth 2.0 resource server to validate Okta-issued access tokens and protect API endpoints.

```java
// pom.xml dependencies
// <dependency>
//   <groupId>com.okta.spring</groupId>
//   <artifactId>okta-spring-boot-starter</artifactId>
//   <version>3.0.5</version>
// </dependency>

// application.properties
// okta.oauth2.issuer=https://{yourOktaDomain}/oauth2/default
// okta.oauth2.audience=api://default

// SecurityConfig.java
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.web.SecurityFilterChain;

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/api/public/**").permitAll()
                .requestMatchers("/api/**").authenticated()
            )
            .oauth2ResourceServer(oauth2 -> oauth2
                .jwt(jwt -> jwt
                    .jwtAuthenticationConverter(jwtAuthenticationConverter())
                )
            );
        return http.build();
    }
}

// Controller.java
import org.springframework.security.core.annotation.AuthenticationPrincipal;
import org.springframework.security.oauth2.jwt.Jwt;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api")
public class ApiController {

    @GetMapping("/public/hello")
    public String publicHello() {
        return "Hello, World!";
    }

    @GetMapping("/whoami")
    public Map<String, Object> whoami(@AuthenticationPrincipal Jwt jwt) {
        return Map.of(
            "subject", jwt.getSubject(),
            "email", jwt.getClaim("email"),
            "name", jwt.getClaim("name"),
            "claims", jwt.getClaims()
        );
    }

    @GetMapping("/secure/data")
    public Map<String, String> secureData(@AuthenticationPrincipal Jwt jwt) {
        return Map.of(
            "message", "This is protected data",
            "user", jwt.getSubject()
        );
    }
}
```

---

Okta's identity platform is primarily used for implementing secure authentication in web applications, mobile apps, and APIs. Common use cases include building customer-facing applications with social login and self-service registration, securing enterprise applications with SSO and MFA, protecting APIs from unauthorized access, and automating user provisioning between HR systems and downstream applications using SCIM. The redirect authentication model is recommended for most applications as it provides the highest security, while embedded authentication with the Sign-In Widget offers more customization options.

Integration patterns typically involve configuring an Okta application, implementing OAuth 2.0/OIDC flows using Okta SDKs or direct API calls, and validating tokens on your resource servers. For server-side applications, use the Authorization Code flow with client credentials stored securely. For SPAs and mobile apps, use Authorization Code with PKCE. For machine-to-machine communication, use the Client Credentials flow. Event hooks enable real-time integration with external systems when user lifecycle events occur in Okta, while SCIM provisioning automates user synchronization between Okta and your applications.