Skip to main content

​
Overview

The DEVision Job Manager API provides programmatic access to company registration, authentication, profile management, job posting, applicant search, and premium subscription features. This API is designed for the Job Manager subsystem of the DEVision job portal platform.

Authentication

Company registration, login, SSO, and token management

Company Profile

Profile CRUD operations and media management

Job Posts

Job lifecycle management and application tracking

Subscription

Premium subscriptions and payment processing

​
Base URL

All API requests should be made to the following base URL: 
https://api.jm.saintgiong.ttr.gg/api/v1/sgjm
For development and testing: 
http://localhost:8080/api/v1/sgjm

​
Authentication

The DEVision API uses JWE (JSON Web Encryption) tokens for authentication. All authenticated endpoints require a valid Bearer token in the Authorization header.

​
Token Format

Authorization: Bearer <jwe_token>

​
Token Lifecycle

1

Login/Register

Authenticate via credentials or SSO to receive access and refresh tokens
2

Access Token

Short-lived token (15 minutes) for API requests
3

Refresh Token

Long-lived token (7 days) to obtain new access tokens
4

Token Revocation

Tokens can be revoked on logout or security events via Redis blocklist

​
Security Scheme

{
  "securitySchemes": {
    "bearerAuth": {
      "type": "http",
      "scheme": "bearer",
      "bearerFormat": "JWE"
    }
  }
}

​
Error Response Format

All API errors follow a consistent format: 
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Email format is invalid",
    "details": {
      "field": "email",
      "constraint": "must be a valid email address"
    }
  },
  "timestamp": "2025-11-28T10:30:00Z",
  "path": "/api/v1/auth/register"
}

​
Error Codes

CodeHTTP StatusDescription
VALIDATION_ERROR400Request validation failed
UNAUTHORIZED401Invalid or expired token
FORBIDDEN403Insufficient permissions
NOT_FOUND404Resource not found
CONFLICT409Resource already exists
RATE_LIMITED429Too many requests
INTERNAL_ERROR500Server error

​
Rate Limiting

API requests are rate-limited to ensure fair usage:
TierRequests per MinuteBurst Limit
Free6010
Premium30050
Rate limit headers are included in all responses: 
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1701234567

​
API Versioning

The API uses URL-based versioning. The current version is v1: 
/api/v1/sgjm/auth/login
/api/v1/sgjm/companies/{id}/profile
/api/v1/sgjm/jobs/{id}

​
Content Types

All requests and responses use JSON: 
Content-Type: application/json
Accept: application/json
For file uploads (media), use multipart form data: 
Content-Type: multipart/form-data

​
Pagination

List endpoints support cursor-based pagination: 
{
  "data": [...],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 150,
    "hasMore": true
  }
}
Query parameters:
  • limit - Number of items per page (default: 20, max: 100)
  • offset - Number of items to skip

​
API Endpoints Overview

​
Authentication

MethodEndpointDescription
POST/api/v1/sgjm/auth/registerRegister new company
POST/api/v1/sgjm/auth/loginLogin with credentials
POST/api/v1/sgjm/auth/sso/googleGoogle SSO authentication
POST/api/v1/sgjm/auth/logoutRevoke tokens
POST/api/v1/sgjm/auth/refreshRefresh access token

​
Company Profile

MethodEndpointDescription
GET/api/v1/sgjm/companies/{id}/profileGet company profile
PUT/api/v1/sgjm/companies/{id}/profileUpdate company profile
POST/api/v1/sgjm/companies/{id}/mediaUpload media files
DELETE/api/v1/sgjm/companies/{id}/media/{mediaId}Delete media

​
Job Posts

MethodEndpointDescription
GET/api/v1/sgjm/jobsList company job posts
POST/api/v1/sgjm/jobsCreate job post
GET/api/v1/sgjm/jobs/{id}Get job post details
PUT/api/v1/sgjm/jobs/{id}Update job post
DELETE/api/v1/sgjm/jobs/{id}Delete job post
GET/api/v1/sgjm/jobs/{id}/applicationsList applications
PATCH/api/v1/sgjm/jobs/{id}/applications/{appId}Update application status

​
Subscription

MethodEndpointDescription
GET/api/v1/sgjm/subscriptions/statusGet subscription status
POST/api/v1/sgjm/subscriptions/checkoutInitiate payment
POST/api/v1/sgjm/subscriptions/webhookStripe webhook handler
MethodEndpointDescription
POST/api/v1/sgjm/search/applicantsSearch applicants (Premium)
GET/api/v1/sgjm/search/profilesList saved search profiles
POST/api/v1/sgjm/search/profilesCreate search profile
Detailed request/response schemas for each endpoint will be added in Milestone 2 implementation phase.