Guides
Start typing to search…

Getting Started with the EvangelOS API

A complete guide to authenticating and making your first request to the EvangelOS API. Get up and running in minutes with session-based authentication.

Welcome, developer! We're excited to see what you'll build with the EvangelOS Core API. This powerful RESTful API allows you to securely connect your applications and services to church data, whether you're building custom reports, mobile apps for members, or integrating with other services.

Prerequisites

Before you begin, ensure you have:

  • An active EvangelOS account with dashboard access
  • Login credentials for your organization
  • Basic familiarity with REST APIs and cURL (or your preferred HTTP client)
  • A development environment for testing API calls

What You'll Learn

In this guide, you'll:

  1. ✅ Understand EvangelOS API authentication
  2. ✅ Set up session-based authentication
  3. ✅ Make your first authenticated request
  4. ✅ Handle common authentication scenarios
  5. ✅ Know what to do next

Quick Overview: Your Path to Success

Authenticate

Log in to establish a secure session

Verify Access

Confirm your session is working correctly

Start Building

Explore endpoints and build your integration

🔐 Authenticate with EvangelOS

The EvangelOS API uses session-based authentication. After a successful login, a session cookie (connect.sid) is set that you'll include with all subsequent API requests.

🔒

Security Note Session cookies are like temporary passwords. Never commit them to version control, and they'll expire automatically for security.

Step 1: Log In to Create a Session

curl -X POST \
  https://api.evangelos.app/api/auth/login \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{
    "username": "your_username_or_email",
    "password": "your_password"
  }'

Expected Login Response

✅ Success (Status Code: 200)

{
  "success": true,
  "message": "Login successful",
  "user": {
    "id": "user_123",
    "email": "[email protected]",
    "organizationId": "org_abc"
  }
}

❌ Failed Login (Status Code: 401)

{
  "error": "Invalid credentials",
  "message": "The username or password you entered is incorrect."
}
✅

Success Tip Save your session using cookie jars (-c cookies.txt in cURL) or session objects in your programming language for easier testing.

🔍 Verify Your Authentication

Now that you're logged in, let's verify your session is working by checking your authentication status.

curl -X GET \
  https://api.evangelos.app/api/auth/status \
  -b cookies.txt

Expected Authentication Status Response

✅ Successfully Authenticated (Status Code: 200)

{
  "authenticated": true,
  "session": {
    "type": "user",
    "userId": "user_123",
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Doe",
    "organizationId": "org_abc",
    "role": "site_admin",
    "permissions": ["members:view", "events:create", "reports:generate"]
  },
  "user": {
    "id": "user_123",
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Doe",
    "organizationId": "org_abc",
    "role": "site_admin",
    "isActive": true
  }
}

❌ Not Authenticated (Status Code: 401)

{
  "authenticated": false,
  "message": "No valid session found"
}
🎉

Congratulations! If you received a 200 OK response with authenticated: true, you've successfully authenticated with the EvangelOS API and you're ready to start making requests!

Troubleshooting Common Issues

Problem: Getting 401 Unauthorized on subsequent requests

Solution: Your session cookie may have expired or wasn't saved properly. Try logging in again and ensure you're including the session cookie with each request.

Problem: CORS errors when making requests from a browser

Solution: Session-based authentication requires same-origin requests or proper CORS configuration. For browser-based applications, ensure your domain is whitelisted or consider using the API from your backend instead.

Problem: "Invalid credentials" error during login

Solutions:

  • Double-check your username/email and password
  • Ensure you're using the correct EvangelOS organization credentials
  • Try logging into the web dashboard first to verify your credentials

Problem: Session works locally but not in production

Solution: Ensure your production environment can properly handle and store session cookies. Some serverless environments may need special cookie handling configuration.

Problem: Getting empty or unexpected responses

Solution: Check that your Content-Type header is set to application/json for POST requests, and that you're properly parsing JSON responses.

🚀 Next Steps

Now that you're successfully authenticated, you're ready to explore the full power of the EvangelOS API!

Explore Core Concepts

Learn about key data models, permissions, and API patterns

Browse API Reference

Discover all available endpoints with interactive examples

Common Use Cases

See practical examples for member management, events, and reporting

SDKs & Libraries

Find official libraries for your preferred programming language

What to Explore First

Based on your development goals, here are some recommended next steps:

💡

Pro Tip All API endpoints in our interactive documentation will automatically use your current session, so you can test requests directly from the browser!

🛠️ Quick Reference

Base URL

https://api.evangelos.app

Authentication Headers

Include your session cookie with every request:

--cookie "connect.sid=YOUR_SESSION_COOKIE_VALUE"

Common Response Codes

  • 200: Success
  • 401: Authentication required or session expired
  • 403: Insufficient permissions
  • 404: Resource not found
  • 429: Rate limit exceeded

Ready to build something amazing? Let's go! 🎯

Updated 2 days ago