Integrating Third-Party Applications

This section describes how to integrate external applications with the gIQ Marketplace using OAuth 2.0 authentication. Third-party applications can authenticate users and access gIQ resources through a secure token-based workflow.

Audience: External application developers integrating with gIQ Marketplace

Prerequisites:

• Client credentials (client_id and client_secret) provided by Space42
• Third-party application registered in gIQ Marketplace
• Access to gIQ API endpoints

Integration Workflow

The integration process uses OAuth 2.0 with a custom external grant type. The workflow involves the following parties:

• Space42: Provides credentials and registers the application
• gIQ Marketplace: Generates access codes and authenticates requests
• Third-party Application: Exchanges codes for tokens and validates users
• End User: Initiates the connection through the marketplace

Step 1: Obtain Client Credentials

Space42 provides the following credentials to identify your application:

• client_id: Unique identifier for your application
• client_secret: Confidential key for authentication

Create the OAuth Client Header

Generate the OAuth_Client header by encoding your credentials in Base64 format:

OAuth_Client = Base64_Encoding(client_id:client_secret)

Example:

client_id: myapp123
client_secret: secret456
OAuth_Client: Base64(myapp123:secret456) = bXlhcHAxMjM6c2VjcmV0NDU2

warning

Store the client_secret securely. Never expose it in client-side code or public repositories.

Step 2: Register Your Application

Space42 registers your third-party application in the gIQ Marketplace. This step is performed by Space42 administrators and includes:

• Application name and description
• Redirect URL for your application
• Required permissions and scopes

note

Contact Space42 support to initiate the registration process for your application.

Step 3: Handle User Redirection from gIQ

When a user selects your application in the gIQ Marketplace, the following occurs:

1. gIQ generates a temporary, single-use access_code for the user
2. gIQ redirects the user to your application URL with the access code as a parameter

Redirect URL format:

https://yourapp.example.com/giq/?accessCode=<access_code>

Example:

https://alphageo.ai/giq/?accessCode=a1b2c3d4e5f6

important

The access_code is valid for a single use only and expires after a short period. Exchange it for an access token immediately upon receipt.

Step 4: Exchange Access Code for Access Token

Your application must call the gIQ OAuth token endpoint to exchange the access code for an access token.

Request Format

Endpoint: POST /oauth/token

Headers:

• Authorization: Basic <OAuth_Client>

Form Parameters:

• grant_type: "external"
• access_code: The code received from the redirect
• type: "EXTERNAL_ACCESS"

Example Request

curl --location 'https://<giq_app_url>/oauth/token' \
--header 'Authorization: Basic <OAuth_Client>' \
--form 'grant_type="external"' \
--form 'access_code="<access_code>"' \
--form 'type="EXTERNAL_ACCESS"'

Successful Response

HTTP Status: 200 OK

{
    "access_token": "eyJhbGciO........",
    "token_type": "bearer",
    "refresh_token": "eyJhbGciOiJS...............",
    "expires_in": 43199,
    "scope": "read write",
    "jti": ""
}

Response Parameters:

• access_token: Bearer token for API authentication (valid for ~12 hours)
• token_type: Always "bearer"
• refresh_token: Token to obtain a new access token without re-authentication
• expires_in: Token validity period in seconds (43199 = ~12 hours)
• scope: Granted permissions
• jti: JWT token identifier

Error Response

HTTP Status: 400 Bad Request

{
    "error": "invalid_access_code",
    "error_description": "access code expired"
}

Common Error Scenarios:

• Access code already used
• Access code expired
• Invalid OAuth client credentials
• Malformed request

Step 5: Validate User and Retrieve User Information

After obtaining the access token, validate the user and retrieve their profile information.

Request Format

Endpoint: GET /api/users/me

Headers:

• Authorization: <access_token>

Example Request

curl 'https://<giq_app_url>/api/users/me' \
-H 'Authorization: eyJhbGciO........'

Successful Response

HTTP Status: 200 OK

{
  "id": "9c3b19a8-b730-2096-a328-8843b5d7cd14",
  "username": "123",
  "fullname": "123",
  "hasAvatar": false,
  "email": "123@test.com",
  "lastLogin": 1686733042675,
  "active": true,
  "language": "EN",
  "forceResetPassword": false,
  "tenantId": "1234567890",
  "modifiedAt": 1683017409280,
  "createdBy": "admin",
  "createdAt": 1670563910209,
  "expireAt": 1670963910209
}

Response Parameters:

Parameter	Type	Description
id	String (UUID)	Unique user identifier
username	String	User's login name
fullname	String	User's display name
hasAvatar	Boolean	Indicates if user has a profile picture
email	String	User's email address
lastLogin	Number	Last login timestamp (Unix epoch milliseconds)
active	Boolean	User account status
language	String	Preferred language code
forceResetPassword	Boolean	Password reset requirement flag
tenantId	String	Organization/tenant identifier
modifiedAt	Number	Last profile modification timestamp (Unix epoch milliseconds)
createdBy	String	Administrator who created the account
createdAt	Number	Account creation timestamp (Unix epoch milliseconds)
expireAt	Number	Account expiration timestamp (Unix epoch milliseconds)

Error Response

HTTP Status: 401 Unauthorized

{
  "error": "invalid_token",
  "error_description": "Invalid access token: abc1234567890"
}

Common Error Scenarios:

• Expired access token
• Malformed access token
• Revoked access token
• Missing Authorization header

---

Alternative Authentication Method: Direct Token Validation

For simpler integrations where OAuth flow is not required, gIQ supports direct token-based authentication.

Workflow

1. gIQ redirects the user to your application with an identity token

Redirect URL format:

https://yourapp.example.com/giq/?token=<identity_token>

2. Your application validates the token by calling the user validation endpoint

Example Request

curl 'https://<giq_app_url>/api/users/me' \
-H 'Authorization: <identity_token>'

Responses

The response format is identical to Step 5 (Validate User and Retrieve User Information):

• Success: HTTP 200 with user profile
• Failure: HTTP 401 with error details

note

This method provides a simpler authentication flow but may offer limited functionality compared to the full OAuth integration.

---

Security Considerations

Token Management

• Store tokens securely: Use encrypted storage for access tokens and refresh tokens
• Implement token refresh: Use the refresh token to obtain new access tokens before expiration
• Handle expiration gracefully: Implement automatic re-authentication when tokens expire
• Validate on every request: Always validate the access token before trusting user information

Client Secret Protection

• Never expose client secrets: Keep client_secret in server-side code only
• Rotate credentials regularly: Request new credentials periodically from Space42
• Monitor for unauthorized access: Track failed authentication attempts

Error Handling

• Log authentication failures: Monitor for suspicious patterns
• Provide clear user feedback: Display appropriate error messages without exposing sensitive details
• Implement rate limiting: Prevent brute-force attacks on token endpoints

---

API Reference Summary

Token Exchange Endpoint

POST /oauth/token
Authorization: Basic <OAuth_Client>
Content-Type: application/x-www-form-urlencoded

grant_type=external&access_code=<code>&type=EXTERNAL_ACCESS

User Validation Endpoint

GET /api/users/me
Authorization: <access_token>

---

Next Steps

After successfully integrating your application:

1. Test thoroughly: Validate the complete authentication flow in a staging environment
2. Implement error handling: Add robust error handling for all API calls
3. Add token refresh: Implement automatic token refresh using the refresh_token
4. Monitor usage: Track authentication metrics and user activity
5. Request production credentials: Contact Space42 to obtain production client credentials

---

Appendix: Code Examples

Python Example: Token Exchange

import requests
import base64

def exchange_access_code(client_id, client_secret, access_code, giq_url):
    # Create OAuth Client header
    credentials = f"{client_id}:{client_secret}"
    oauth_client = base64.b64encode(credentials.encode()).decode()
    
    # Make token request
    response = requests.post(
        f"{giq_url}/oauth/token",
        headers={
            "Authorization": f"Basic {oauth_client}"
        },
        data={
            "grant_type": "external",
            "access_code": access_code,
            "type": "EXTERNAL_ACCESS"
        }
    )
    
    if response.status_code == 200:
        return response.json()
    else:
        raise Exception(f"Token exchange failed: {response.json()}")

# Usage
token_data = exchange_access_code(
    client_id="your_client_id",
    client_secret="your_client_secret",
    access_code="received_access_code",
    giq_url="https://giq.example.com"
)

access_token = token_data["access_token"]

Python Example: User Validation

import requests

def get_user_info(access_token, giq_url):
    response = requests.get(
        f"{giq_url}/api/users/me",
        headers={
            "Authorization": access_token
        }
    )
    
    if response.status_code == 200:
        return response.json()
    else:
        raise Exception(f"User validation failed: {response.json()}")

# Usage
user_info = get_user_info(
    access_token="your_access_token",
    giq_url="https://giq.example.com"
)

print(f"Authenticated user: {user_info['email']}")

Additional Resources

• Contact Space42 Tech Support for registration assistance
• Review gIQ API documentation for additional endpoints