PowerSchool API Postman Collection, feel free to copy to fork it

Overview

This collection provides a complete, production-ready setup for working with PowerSchool APIs. It implements automatic OAuth authentication with token validation, eliminating manual token management and enabling seamless multi-environment workflows.

Key Features

🔐 Automatic Authentication

• Zero Manual Token Management: Tokens are obtained and validated automatically before every request
• Smart Token Validation: Validates tokens against the PowerSchool metadata endpoint (/ws/v1/metadata)
• Auto-Refresh on Expiry: Automatically refreshes expired or invalid tokens
• Bearer Token Headers: All requests automatically include properly formatted Authorization: Bearer {{psAuthToken}} headers

🌍 Multi-Environment Support

• Different PowerSchool Instances: Easily switch between multiple PowerSchool servers (Development, Staging, Production)
• Credential Isolation: Each environment has its own psURL, psClientID, and psClientSecret
• Shared Token Storage: psAuthToken stored at collection level, shared across all environments
• One-Click Switching: Select different environments from Postman dropdown

✅ Token Validation

• Metadata Endpoint Check: Validates token by calling /ws/v1/metadata
• Plugin ID Detection: Confirms token validity by checking for plugin_id in response
• Automatic Recovery: If token is invalid, automatically obtains a new one
• Error Prevention: Detects authentication issues before they cause request failures

📋 Complete Request Examples

• PowerSchool OAuth Request: Direct OAuth endpoint for manual token retrieval
• Get Metadata (with token): Example of authenticated request
• Get Metadata (without token): Shows public metadata access
• Get Students By District: Production-ready example with auto-auth

How It Works

Request Flow

When you click Send on any request:

1. Collection Pre-request Script Runs
   ↓
2. Check: Does psAuthToken exist?
   ├─ NO  → Obtain new token via OAuth
   ├─ YES → Validate token via /ws/v1/metadata
   │        ├─ Valid (has plugin_id) → Proceed
   │        └─ Invalid (no plugin_id) → Get new token
   ↓
3. Token stored in psAuthToken (collection variable)
   ↓
4. Request executes with Authorization: Bearer {{psAuthToken}}
   ↓
5. Response received

Token Validation Logic

Valid Token Response:

{
    "metadata": {
        "plugin_id": 15334,
        "powerschool_version": "25.7.0.1.252121950",
        ...
    }
}

Invalid Token Response:

{
    "metadata": {
        "district_timezone": "Asia/Riyadh",
        ...
        (NO plugin_id field)
    }
}

The script detects missing plugin_id and automatically refreshes the token.

Setup Instructions

1. Create Environments

For each PowerSchool instance, create an environment with:

2. Collection Variables

The collection already includes:

• psAuthToken – Auto-populated by OAuth script (do not edit)

3. Select Environment

Before making requests, select your environment from the Postman dropdown (top-right).

4. Make Requests

Click Send on any request. The collection pre-request script handles all authentication automatically.

Collection Structure

PowerSchool API Postman Collection
├── Authentication (Collection-level Pre-request Script)
│   ├── Token validation against /ws/v1/metadata
│   ├── Auto-refresh on expiry
│   └── Error handling
│
├── PowerSchool OAuth Request (POST)
│   └── Direct OAuth endpoint access
│   └── Manual token retrieval (for testing)
│
├── Get Metadata (with token) (GET)
│   └── Authenticated metadata endpoint
│   └── Shows valid token usage
│
├── Get Metadata (without token) (GET)
│   └── Public metadata access
│   └── Shows response without authentication
│
└── Get Students By District (GET)
    └── Example authenticated API request
    └── Returns district student data

Variables Reference

Collection Variables

• psAuthToken – OAuth access token (auto-populated, do NOT manually edit)

Environment Variables (Set per PowerSchool instance)

• psURL – PowerSchool domain (e.g., https://ps.asb.bh)
• psClientID – OAuth client ID from PowerSchool admin
• psClientSecret – OAuth client secret from PowerSchool admin

Console Logging

The collection provides detailed console logging for debugging:

Successful Token Validation:

⚠ Validating existing token...
✓ Token is valid. Plugin ID: 15334
✓ Auth token already set, proceeding...

Token Refresh:

⚠ Validating existing token...
⚠ Token is invalid. No plugin_id in metadata response
⚠ Token is invalid, getting new one...
⚠ Getting new authentication token...
✓ New token obtained successfully

Missing Credentials:

✗ Missing required variables: psURL, psClientID, or psClientSecret

Open Postman Console (bottom-left) to view all logs.

Common Use Cases

Adding New PowerSchool API Endpoints

1. Click “+” to add new request to collection
2. Set method and URL: {{psURL}}/ws/v1/[endpoint]
3. Add headers:
   • Authorization: Bearer {{psAuthToken}}
   • Accept: application/json
4. Click Save

The collection pre-request script automatically handles authentication for all new requests.

Switching Between PowerSchool Instances

1. Open Postman
2. Click environment dropdown (top-right)
3. Select desired environment
4. Make request – collection script uses selected environment’s credentials

Manual OAuth Testing

1. Click PowerSchool OAuth Request
2. Verify environment is selected
3. Click Send
4. Token is extracted and stored in psAuthToken
5. Check console for success/error messages

Validating Token Status

1. Click Get Metadata (with token)
2. Click Send
3. Response shows current metadata with or without plugin_id
4. If plugin_id is present, token is valid
5. If plugin_id is missing, token will auto-refresh on next request

Error Handling

“Missing required variables”

Cause: Environment variables not set Solution: Add psURL, psClientID, psClientSecret to selected environment

“OAuth request failed with status 401”

Cause: Incorrect credentials Solution: Verify OAuth client ID and secret in PowerSchool admin portal

“Token is invalid. No plugin_id in metadata response”

Cause: Token lacks required permissions or is expired Solution: Token auto-refreshes automatically on next request

“Authorization header empty”

Cause: Token didn’t load before request executed Solution: Wait a moment and retry, or manually run OAuth request first

Best Practices

Security

• ✓ Never commit real credentials to version control
• ✓ Use Postman environments to store sensitive data
• ✓ Treat psClientSecret like a password
• ✓ Rotate OAuth credentials periodically

Organization

• ✓ Use meaningful request names
• ✓ Group related endpoints in folders
• ✓ Document expected responses in request descriptions
• ✓ Keep collection pre-request script clean and updated

Maintenance

• ✓ Test collection monthly with all environments
• ✓ Monitor PowerSchool API changes
• ✓ Update endpoints as PowerSchool APIs evolve
• ✓ Keep OAuth credentials current

API Endpoints Included

Next Steps

1. Create Environments: Add your PowerSchool instances as separate environments
2. Set Credentials: Configure psURL, psClientID, psClientSecret per environment
3. Test Collection: Run requests and verify token validation in console
4. Extend Collection: Add more endpoints as needed using the same patterns

Support & Troubleshooting

Check Console Logs

Open Postman Console (bottom of screen) to see detailed execution logs including:

• Token validation results
• OAuth request status
• Variable resolution
• Error messages

Validate Token Manually

1. Run Get Metadata (with token)
2. Look for "plugin_id" in response
3. If present: Token is valid ✓
4. If missing: Token needs refresh (auto-handled)

Test OAuth Endpoint

1. Run PowerSchool OAuth Request
2. Check console for:
   • ✓ Set psAuthToken as [token] – Success
   • ✗ OAuth failed... – Check credentials

FAQ

Q: Do I need to manually get a token? A: No. The collection automatically manages tokens. Manual OAuth request is only for testing.

Q: Can I use this with multiple PowerSchool instances? A: Yes. Create separate environments for each instance and switch between them.

Q: What happens if my token expires? A: The collection automatically detects expiry and refreshes the token before the next request.

Q: Where is my token stored? A: In the collection variable psAuthToken. It persists across environment switches.

Q: Can I see what the script is doing? A: Yes. Open Postman Console (Ctrl+Alt+C or Cmd+Option+C) to view detailed logs.

Q: How often do tokens refresh? A: Only when they expire or are invalid. Valid tokens are reused across requests.

Author: Prince PARK
Version: 1.0
Last Updated: March 26, 2026
Created For: PowerSchool API Integration
Requires: Postman 10.0+